From 8e49ba20ecc8697c2a5efcd781804cc492b1587c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Fri, 12 Jan 2018 14:38:07 +0100 Subject: [PATCH] doc: building docs updates. Proofread everything, make the packages the first choice (and manual build only as a backup catch-all solution), don't force the users to CMake but provide useful snippets to show how to use the libs from CMake. --- doc/building.dox | 675 +++++++++++------- doc/getting-started.dox | 23 +- doc/mainpage.dox | 63 +- doc/namespaces.dox | 284 ++++++-- src/Magnum/Audio/Extensions.h | 19 +- src/Magnum/Extensions.h | 13 +- src/Magnum/OpenGLTester.h | 28 +- src/Magnum/Platform/AbstractXApplication.h | 4 +- src/Magnum/Platform/AndroidApplication.h | 44 +- src/Magnum/Platform/GlfwApplication.h | 28 +- src/Magnum/Platform/GlutApplication.h | 27 +- src/Magnum/Platform/GlxApplication.h | 22 +- src/Magnum/Platform/Sdl2Application.h | 28 +- .../Platform/WindowlessCglApplication.h | 23 +- .../Platform/WindowlessEglApplication.h | 20 +- .../Platform/WindowlessGlxApplication.h | 19 +- .../Platform/WindowlessIosApplication.h | 25 +- .../Platform/WindowlessWglApplication.h | 19 +- .../WindowlessWindowsEglApplication.h | 22 +- src/Magnum/Platform/XEglApplication.h | 22 +- src/Magnum/Trade/AbstractImageConverter.h | 17 +- src/Magnum/Trade/AbstractImporter.h | 29 +- src/MagnumPlugins/MagnumFont/MagnumFont.h | 93 +-- .../MagnumFontConverter/MagnumFontConverter.h | 17 +- src/MagnumPlugins/ObjImporter/ObjImporter.h | 17 +- .../TgaImageConverter/TgaImageConverter.h | 23 +- src/MagnumPlugins/TgaImporter/TgaImporter.h | 13 +- .../WavAudioImporter/WavImporter.h | 17 +- 28 files changed, 1040 insertions(+), 594 deletions(-) diff --git a/doc/building.dox b/doc/building.dox index c80bbc79b..0fc74bfa7 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -31,38 +31,170 @@ namespace Magnum { @tableofcontents @m_footernavigation +@section building-packages Prepared packages + +The easiest way to install Magnum is to use one of the ready-made packages for +your platform of choice. See @ref building-manual if you want to have more +control and @ref building-cross for cross-compiling to other platforms. + +- @ref building-packages-arch +- @ref building-packages-deb +- @ref building-packages-gentoo +- @ref building-packages-brew + +The engine itself is kept as small as possible with only minimal dependencies. +In order to use extra functionality, often depending on external libraries, you +need to build also packages of additional repositories. Various importer +plugins for image, audio and 3D model formats are maintained in the +@ref building-plugins "Plugins repository", integration with external math and +physics libraries is provided by @ref building-integration "Integration libraries" +and other extra features are in the @ref building-extras "Extra libraries". +Various examples are provided by the @ref building-examples "Example repository". + +@subsection building-packages-arch ArchLinux packages + +In `package/archlinux/magnum-git` there is a package for Git development build. +The package is also in AUR as +[magnum-git](https://aur.archlinux.org/packages/magnum-git/). It depends on the +@ref building-corrade-packages-arch "Corrade ArchLinux package". + +There are also quite a few development packages for native builds, OpenGL ES +builds, cross-compilation for Emscripten, Android and MinGW or various +sanitizer/coverage builds. See the PKGBUILD files in the `package/archlinux` +directory. They allow you to build and install the package directly from the +source tree. Example usage: + +@code{.sh} +git clone git://github.com/mosra/magnum && cd magnum +cd package/archlinux +makepkg -fp PKGBUILD # or any other PKGBUILD file +@endcode + +In most cases the development PKGBUILDs also contain a @cb{.sh} check() @ce +function which will run all unit tests before packaging. That might sometimes +fail or take too long, pass `--nocheck` to `makepkg` to skip that. + +Once built, install the package using `pacman`: + +@code{.sh} +sudo pacman -U magnum-*.pkg.tar.xz +@endcode + +Edit the PKGBUILDs if you want to pass additional flags to CMake or +@ref building-features "enable / disable additional features". + +There are also ArchLinux packages for @ref building-plugins-packages-arch "Magnum Plugins", @ref building-integration-packages-arch "Magnum Integration", +@ref building-extras-packages-arch "Magnum Extras" and +@ref building-examples-packages-arch "Magnum Examples". + +@subsection building-packages-deb Packages for Debian, Ubuntu and derivatives + +The `package/debian/` directory contains all files needed for building Debian +packages. You need the @ref building-corrade-packages-deb "Corrade Debian package" +installed and in addition also the `dpkg-dev` and `debhelper` packages. +Building is easy, just change directory to package root, link or copy +`package/debian` directory there and run `dpkg-buildpackage`: + +@code{.sh} +git clone git://github.com/mosra/magnum && cd magnum +ln -s package/debian . +dpkg-buildpackage +@endcode + +This will compile binary and development packages, which will then appear in a +parent directory. Install them using `dpkg`: + +@code{.sh} +sudo dpkg -i ../magnum*.deb +@endcode + +If you want to pass additional flags to CMake or +@ref building-features "enable / disable additional features", add them to +`dh_auto_configure` at the bottom of `debian/rules`. Watch out, as +indentation has to be done using tabs, not spaces. + +There are also Debian packages for @ref building-plugins-packages-deb "Magnum Plugins", @ref building-integration-packages-deb "Magnum Integration", +@ref building-extras-packages-deb "Magnum Extras" and +@ref building-examples-packages-deb "Magnum Examples". + +@subsection building-packages-gentoo Gentoo Linux ebuilds + +Gentoo Git ebuild is available in the `package/gentoo` directory. Get the +@ref building-corrade-packages-gentoo "Corrade Gentoo package" first and then +build and install Magnum like this: + +@code{.sh} +git clone git://github.com/mosra/magnum && cd magnum +cd package/gentoo +sudo ebuild dev-libs/magnum/magnum-99999.ebuild manifest clean merge +@endcode + +If you want to pass additional flags to CMake or +@ref building-features "enable / disable additional features", add them to +`mycmakeargs` in the `*.ebuild` file. + +There are also Gentoo packages for @ref building-plugins-packages-gentoo "Magnum Plugins", @ref building-integration-packages-gentoo "Magnum Integration", +@ref building-extras-packages-gentoo "Magnum Extras" and +@ref building-examples-packages-gentoo "Magnum Examples". + +@subsection building-packages-brew Homebrew formulas for macOS + +macOS [Homebrew](https://brew.sh) formulas building the latest Git revision are +in the `package/homebrew` directory. Either use the `*.rb` files directly or +use the tap at https://github.com/mosra/homebrew-magnum. When installing from +the `*.rb` files you need to install the +@ref building-corrade-packages-brew "Corrade Homebrew package" first, otherwise +you can do just this: + +@code{.sh} +brew install --HEAD mosra/magnum/corrade +brew install --HEAD mosra/magnum/magnum +@endcode + +If you want to pass additional flags to CMake or +@ref building-features "enable / disable additional features", edit the `*.rb` +file. + +There are also Homebrew packages for @ref building-plugins-packages-brew "Magnum Plugins", @ref building-integration-packages-brew "Magnum Integration", +@ref building-extras-packages-brew "Magnum Extras" and +@ref building-examples-packages-brew "Magnum Examples". + +@section building-manual Manual build + Minimal set of tools and libraries required for building is: - C++ compiler with good C++11 support. Compilers which are tested to have everything needed are **GCC** >= 4.7, **Clang** >= 3.1 and **MSVC** >= 2015. On Windows you can also use **MinGW-w64**. - **CMake** >= 2.8.12 -- **Corrade** - Plugin management and utility library. See +- **Corrade** --- Plugin management and utility library. See @ref building-corrade "Corrade download and installation guide" for more information. -Note that full feature set is available only on GCC 4.8.1 and Clang 3.1. +Additional functionality is provided separately in +@ref building-plugins "Magnum Plugins", +@ref building-integration "Magnum Integration", +@ref building-extras "Magnum Extras" and +@ref building-examples "Magnum Examples". -@section building-download Downloading the sources +@subsection building-download Downloading the sources The source is available on GitHub: https://github.com/mosra/magnum. Clone the -repository with your favorite IDE or Git GUI, download currrent snapshot as +repository with your favorite IDE or Git GUI, download currrent snapshot as a compressed archive or use the command line: @code{.sh} git clone git://github.com/mosra/magnum.git @endcode -@section building-compilation Compilation, installation - Relevant information about CMake usage was described in -@ref building-corrade "Corrade download and installation guide", this guide is -assuming you have at least basic knowledge of CMake. +@ref building-corrade-cmake "Corrade download and installation guide", this +guide is assuming you have at least basic knowledge of CMake. @subsection building-linux Via command-line (on Linux/Unix) -On Unix-based OSs, the library (for example with support for SDL2 applications) -can be built and installed using these four commands: +On Unix-based OSes, the library (for example with support for SDL2 +applications) can be built and installed using these four commands: @code{.sh} mkdir build && cd build @@ -70,7 +202,7 @@ cmake .. \ -DCMAKE_INSTALL_PREFIX=/usr \ -DWITH_SDL2APPLICATION=ON make -make install +make install # sudo may be needed @endcode See @ref building-features "below" for additional configuration options. @@ -86,14 +218,15 @@ want to set `CMAKE_INSTALL_RPATH` to `lib/` subdir of given prefix (e.g. @subsection building-windows Building on Windows -On Windows you can use either MinGW-w64 or MSVC 2013 compiler. It's then up to -you whether you will use QtCreator, Visual Studio or do the build from command- -line. Note that for most convenient usage it's best use some dedicated -directory (e.g. `C:/Sys`) for installing dependencies instead of putting each -dependency to its own directory in `C:/Program Files`. Then add its `bin/` -subdir (e.g. `C:/Sys/bin`) to PATH so all the DLLs are found when running the -executables. If you are using MinGW-w64, the `C:/MinGW` directory is in most -cases already prepared for exactly this. +On Windows you can use either MSVC or the MinGW-w64 compiler. It's then up to +you whether you will use QtCreator, Visual Studio or anoother IDE or do the +build from a command line. Note that for most convenient usage it's best use +some dedicated directory (e.g. `C:/Sys`) for installing dependencies instead of +putting each dependency to its own directory in `C:/Program Files` or +elsewhere. Then you can just add its `bin/` subdir (e.g. `C:/Sys/bin`) to +@cb{.bat} %PATH% @ce so all the DLLs are found when running the executables. If +you are using MinGW-w64, the `C:/MinGW` directory is in most cases already +prepared for exactly this. Then, when running CMake, set `CMAKE_PREFIX_PATH` and `CMAKE_INSTALL_PREFIX` value to that directory (e.g. `-DCMAKE_INSTALL_PREFIX=C:/Sys`). @@ -103,7 +236,7 @@ value to that directory (e.g. `-DCMAKE_INSTALL_PREFIX=C:/Sys`). On Windows CMake by default creates Visual Studio project files. The most straightforward way to build and install the library is again via the -command-line. The bonus point is that you don't even need to wait for Visual +command line. The bonus point is that you don't even need to wait for Visual Studio to load: @code{.bat} @@ -118,88 +251,91 @@ project file generated by CMake in the build directory. @subsubsection building-windows-qtcreator Using QtCreator -On Windows you can also use QtCreator (just QtCreator, you don't need the full -Qt SDK). Configure it to use CMake and either MSVC compiler or MinGW-w64 and -then just open project's root `CMakeLists.txt` file within it. QtCreator then -asks you where to create build directory, allows you to specify initial CMake -parameters (e.g. `CMAKE_PREFIX_PATH` and `CMAKE_INSTALL_PREFIX`) and then you -can just press *Configure* and everything is ready to be built. +On Windows, besides other IDEs, you can also use QtCreator (just QtCreator, you +don't need the full Qt SDK). Configure it to use CMake and either the MSVC +compiler or MinGW-w64 and then just open project's root `CMakeLists.txt` file +within it. QtCreator then asks you where to create build directory, allows you +to specify initial CMake parameters (e.g. `CMAKE_PREFIX_PATH` and +`CMAKE_INSTALL_PREFIX`) and then you can just press *Configure* and everything +is ready to be built. After the initial import you might want to reconfigure some CMake variables, see @ref building-features "below" for more information. -Installation to given prefix can be done from within QtCreator by adding new +Installation to given prefix can be done from within QtCreator by adding a new `make install` build rule. @subsection building-features Enabling or disabling features -The libraries are build as shared by default. If you are developing for +The libraries are build as shared by default. If you are developing for a platform which doesn't support shared libraries or if you just want to link them statically, enable `BUILD_STATIC` to build the libraries as static. -Building of static plugins is controlled with separate `BUILD_PLUGINS_STATIC` +Building of static plugins is controlled with a separate `BUILD_PLUGINS_STATIC` variable. If you plan to use the static libraries and plugins with shared libraries later, enable also position-independent code with `BUILD_STATIC_PIC`. If you want to build with another compiler (e.g. Clang), pass `-DCMAKE_CXX_COMPILER=clang++` to CMake. Libraries and static plugins built in `Debug` configuration (e.g. with -`CMAKE_BUILD_TYPE` set to `Debug`) have `-d` suffix to make it possible to have -both debug and release libraries installed alongside each other. *Dynamic* +`CMAKE_BUILD_TYPE` set to `Debug`) have a `-d` suffix to make it possible to +have both debug and release libraries installed alongside each other. *Dynamic* plugins in `Debug` configuration are installed to `magnum-d` subdirectory -instead of `magnum`. Headers and other files are the same for both. The library -and plugin distinction is handled semi-automatically when using Magnum in -depending projects, see @ref cmake for more information. +instead of `magnum`. Headers and other files are the same for both debug and +release configurations. The library and plugin distinction is handled +semi-automatically when using Magnum in depending projects, see @ref cmake for +more information. The library is constantly evolving and thus some APIs are deprecated and then later removed in favor of better ones. To preserve backwards compatibility, -Magnum is by default built with all deprecated APIs. However, to make your -code more robust and future-proof, it's recommended to build the library with -`BUILD_DEPRECATED` disabled. +Magnum is by default built with all deprecated APIs included. However, to make +your code more robust and future-proof, it's recommended to build the library +with `BUILD_DEPRECATED` disabled. -By default the engine is built for desktop OpenGL. Using `TARGET_*` CMake -parameters you can target other platforms. Note that some features are +By default the engine is built for desktop OpenGL. Using the `TARGET_*` CMake +options you can target other platforms. Note that some features are available for desktop OpenGL only, see @ref requires-gl. - `TARGET_GLES` --- Target OpenGL ES. -- `TARGET_GLES2` --- Target OpenGL ES 2.0. Currently enabled by default when - `TARGET_GLES` is set. +- `TARGET_GLES2` --- Target OpenGL ES 2.0 instead of 3.0 and later. Currently + enabled by default when `TARGET_GLES` is set. - `TARGET_DESKTOP_GLES` --- Target OpenGL ES on desktop, i.e. use OpenGL ES - emulation in desktop OpenGL library. Available on Linux and Windows, though + emulation in desktop OpenGL drivers. Available on Linux and Windows, though might not be supported by all drivers. - `TARGET_HEADLESS` --- Build command-line utilities for use on a headless machine. Basically it means that EGL with no display attachment is being used everywhere instead of platform-specific toolkits like CGL, GLX or WGL. - Supported mainly on OpenGL ES drivers, for desktop OpenGL the only driver - that supports this configuration is NVidia >= 355. + Supported mainly on OpenGL ES drivers. -By default the engine is built in a way that allows having multiple -thread-local Magnum contents. This might cause some performance penalties --- if -you are sure that you will never need such feature, you can disable it via the -`BUILD_MULTITHREADED` option. +By default the engine is built in a way that allows having multiple independent +thread-local Magnum contents. This might cause some performance penalties --- +if you are sure that you will never need such feature, you can disable it via +the `BUILD_MULTITHREADED` option. The features used can be conveniently detected in depending projects both in CMake and C++ sources, see @ref cmake and @ref Magnum/Magnum.h for more information. See also @ref corrade-cmake and @ref Corrade/Corrade.h for -additional information. - -By default the engine is built with nearly everything except @ref Audio -library, plugins and application libraries (see below). Using `WITH_*` CMake -parameters you can specify which parts will be built and which not: - -- `WITH_AUDIO` --- @ref Audio library. Depends on **OpenAL** library, not - built by default. -- `WITH_DEBUGTOOLS` --- @ref DebugTools library -- `WITH_MESHTOOLS` --- @ref MeshTools library -- `WITH_PRIMITIVES` --- @ref Primitives library -- `WITH_SCENEGRAPH` --- @ref SceneGraph library. Enabled automatically if - `WITH_SHAPES` is enabled. -- `WITH_SHADERS` --- @ref Shaders library -- `WITH_SHAPES` --- @ref Shapes library. Enables also building of SceneGraph - library. Enabled automatically if `WITH_DEBUGTOOLS` is enabled. -- `WITH_TEXT` --- @ref Text library. Enables also building of TextureTools - library. -- `WITH_TEXTURETOOLS` --- @ref TextureTools library. Enabled automatically if - `WITH_TEXT` or `WITH_DISTANCEFIELDCONVERTER` is enabled. +related info for the Corrade library. + +By default the engine is built with nearly everything except the @ref Audio +library, plugins, command-line utilities and application libraries (see below). +Using the following `WITH_*` CMake options you can specify which parts will +be built and which not: + +- `WITH_AUDIO` --- Build the @ref Audio library. Depends on + [OpenAL](https://www.openal.org/), not built by default. +- `WITH_DEBUGTOOLS` --- Build the @ref DebugTools library. +- `WITH_MESHTOOLS` --- Build the @ref MeshTools library. +- `WITH_PRIMITIVES` --- Build the @ref Primitives library. +- `WITH_SCENEGRAPH` --- Build the @ref SceneGraph library. Enabled + automatically if `WITH_SHAPES` is enabled. +- `WITH_SHADERS` --- Build the @ref Shaders library. +- `WITH_SHAPES` --- Build the @ref Shapes library. Enables also building of + the SceneGraph library. Enabled automatically if `WITH_DEBUGTOOLS` is + enabled. +- `WITH_TEXT` --- Build the @ref Text library. Enables also building of + the TextureTools library. +- `WITH_TEXTURETOOLS` --- Build the @ref TextureTools library. Enabled + automatically if `WITH_TEXT` or `WITH_DISTANCEFIELDCONVERTER` is enabled. There are more involved component dependencies that are not described here (for example the @ref DebugTools has some functionality that gets built only when @@ -208,103 +344,138 @@ other things), but the CMake buildsystem takes care of these and only the relevant toggleable options are shown in CMake GUI or `ccmake`. None of the @ref Platform "application libraries" is built by default (and you -need at least one). Choose the one which suits your requirements and your -platform best: - -- `WITH_ANDROIDAPPLICATION` --- @ref Platform::AndroidApplication "AndroidApplication" -- `WITH_GLFWAPPLICATION` --- @ref Platform::GlfwApplication "GlfwApplication" -- `WITH_GLUTAPPLICATION` --- @ref Platform::GlutApplication "GlutApplication" -- `WITH_GLXAPPLICATION` --- @ref Platform::GlxApplication "GlxApplication" -- `WITH_SDL2APPLICATION` --- @ref Platform::Sdl2Application "Sdl2Application" -- `WITH_XEGLAPPLICATION` --- @ref Platform::XEglApplication "XEglApplication" -- `WITH_WINDOWLESSCGLAPPLICATION` --- @ref Platform::WindowlessCglApplication "WindowlessCglApplication" -- `WITH_WINDOWLESSEGLAPPLICATION` --- @ref Platform::WindowlessEglApplication "WindowlessEglApplication" -- `WITH_WINDOWLESSGLXAPPLICATION` --- @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication" -- `WITH_WINDOWLESSIOSAPPLICATION` --- @ref Platform::WindowlessIosApplication "WindowlessIosApplication" -- `WITH_WINDOWLESSWGLAPPLICATION` --- @ref Platform::WindowlessWglApplication "WindowlessWglApplication" -- `WITH_WINDOWLESSWINDOWSEGLAPPLICATION` --- @ref Platform::WindowlessWindowsEglApplication "WindowlessWindowsEglApplication" - -None of the context libraries is built by default. You need them only if you -choose to not use any application library (see @ref platform-custom for more -information): - -- `WITH_CGLCONTEXT` --- CGL context -- `WITH_EGLCONTEXT` --- EGL context -- `WITH_GLXCONTEXT` --- GLX context -- `WITH_WGLCONTEXT` --- WGL context +need at least one, unless you are handling platform integration yourself --- +see @ref platform-custom for more information). As they are rather tiny, they +are always built as static. Choose the one that suits your requirements and +your platform best: + +- `WITH_ANDROIDAPPLICATION` --- Build the + @ref Platform::AndroidApplication "AndroidApplication" library. Available + only on @ref CORRADE_TARGET_ANDROID "Android". +- `WITH_GLFWAPPLICATION` --- Build the + @ref Platform::GlfwApplication "GlfwApplication" library. Depends on + [GLFW](http://glfw.org). +- `WITH_GLUTAPPLICATION` --- Build the + @ref Platform::GlutApplication "GlutApplication" library. Depends on + [GLUT](http://freeglut.sourceforge.net/). +- `WITH_GLXAPPLICATION` --- Build the + @ref Platform::GlxApplication "GlxApplication" library. Depends on **X11**. +- `WITH_SDL2APPLICATION` --- Build the + @ref Platform::Sdl2Application "Sdl2Application" library. Depends on + [SDL2](http://www.libsdl.org). +- `WITH_XEGLAPPLICATION` --- Build the + @ref Platform::XEglApplication "XEglApplication" library. +- `WITH_WINDOWLESSCGLAPPLICATION` --- Build the + @ref Platform::WindowlessCglApplication "WindowlessCglApplication" library. +- `WITH_WINDOWLESSEGLAPPLICATION` --- Build the + @ref Platform::WindowlessEglApplication "WindowlessEglApplication" library. +- `WITH_WINDOWLESSGLXAPPLICATION` --- Build the + @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication" library. +- `WITH_WINDOWLESSIOSAPPLICATION` --- Build the + @ref Platform::WindowlessIosApplication "WindowlessIosApplication" library. +- `WITH_WINDOWLESSWGLAPPLICATION` --- Build the + @ref Platform::WindowlessWglApplication "WindowlessWglApplication" library. +- `WITH_WINDOWLESSWINDOWSEGLAPPLICATION` --- Build the + @ref Platform::WindowlessWindowsEglApplication "WindowlessWindowsEglApplication" + library. + +None of the context libraries is built by default. Similarly to the application +libraries, they are always built as static. You need them only if you chose to +not use any of the application libraries above (see @ref platform-custom for +more information): + +- `WITH_CGLCONTEXT` --- Build the CGL context handling library. +- `WITH_EGLCONTEXT` --- Build the EGL context handling library. +- `WITH_GLXCONTEXT` --- Build the GLX context handling library. +- `WITH_WGLCONTEXT` --- Build the WGL context handling library. There are also extensions to @ref Corrade::TestSuite::Tester for testing GPU code: -- `WITH_OPENGLTESTER` --- @ref OpenGLTester class. Enables building of one of - `Platform::Windowless*Application` libraries based on platform. +- `WITH_OPENGLTESTER` --- The @ref OpenGLTester class. Enables building of + one of the windowless application libraries based on the target platform. Magnum also contains a set of dependency-less plugins for importing essential -file formats. Additional plugins are provided in separate plugin repository, +file formats. Additional plugins are provided in a separate plugin repository, see @ref building-plugins for more information. None of the plugins is built by default. -- `WITH_MAGNUMFONT` --- @ref Text::MagnumFont "MagnumFont" plugin. Available - only if `WITH_TEXT` is enabled. Enables also building of +- `WITH_MAGNUMFONT` --- Build the @ref Text::MagnumFont "MagnumFont" plugin. + Available only if `WITH_TEXT` is enabled. Enables also building of the @ref Trade::TgaImporter "TgaImporter" plugin. -- `WITH_MAGNUMFONTCONVERTER` --- @ref Text::MagnumFontConverter "MagnumFontConverter" - plugin. Available only if `WITH_TEXT` is enabled. Enables also building of +- `WITH_MAGNUMFONTCONVERTER` --- Build the + @ref Text::MagnumFontConverter "MagnumFontConverter" plugin. Available only + if `WITH_TEXT` is enabled. Enables also building of their @ref Trade::TgaImageConverter "TgaImageConverter" plugin. -- `WITH_OBJIMPORTER` --- @ref Trade::ObjImporter "ObjImporter" plugin. -- `WITH_TGAIMPORTER` --- @ref Trade::TgaImporter "TgaImporter" plugin. -- `WITH_TGAIMAGECONVERTER` --- @ref Trade::TgaImageConverter "TgaImageConverter" +- `WITH_OBJIMPORTER` --- Build the @ref Trade::ObjImporter "ObjImporter" plugin. -- `WITH_WAVAUDIOIMPORTER` --- @ref Audio::WavImporter "WavAudioImporter" +- `WITH_TGAIMPORTER` --- Build the @ref Trade::TgaImporter "TgaImporter" + plugin. +- `WITH_TGAIMAGECONVERTER` --- Build the + @ref Trade::TgaImageConverter "TgaImageConverter" plugin. +- `WITH_WAVAUDIOIMPORTER` --- Build the @ref Audio::WavImporter "WavAudioImporter" plugin. Available only if `WITH_AUDIO` is enabled. -There are also a few command-line utilities, also disabled by default: +There are also a few command-line utilities, also all disabled by default: -- `WITH_MAGNUMINFO` --- @ref magnum-info "magnum-info" executable, provides - information about the engine and OpenGL capabilities. Depends on some - windowless application library. -- `WITH_AL_INFO` --- @ref magnum-al-info "magnum-al-info" executable, - provides information about OpenAL capabilities. -- `WITH_DISTANCEFIELDCONVERTER` --- @ref magnum-distancefieldconverter "magnum-distancefieldconverter" +- `WITH_MAGNUMINFO` --- Build the @ref magnum-info "magnum-info" executable, + which provides information about the engine and OpenGL capabilities. + Enables building of one of the windowless application libraries based on + the target platform. +- `WITH_AL_INFO` --- Build the @ref magnum-al-info "magnum-al-info" + executable, which provides information about OpenAL capabilities. +- `WITH_DISTANCEFIELDCONVERTER` --- Build the + @ref magnum-distancefieldconverter "magnum-distancefieldconverter" executable for converting black&white images to distance field textures. - Enables also building of @ref TextureTools library. Available only on - desktop GL, depends on some windowless application library. -- `WITH_FONTCONVERTER` --- @ref magnum-fontconverter "magnum-fontconverter" - executable for converting fonts to raster ones. Enables also building of - @ref Text library. Available only on desktop GL, depends on some windowless - application library. -- `WITH_IMAGECONVERTER` --- @ref magnum-imageconverter "magnum-imageconverter" + Enables also building of the @ref TextureTools library. Available only on + desktop GL. Enables building of one of the windowless application libraries + based on the target platform. +- `WITH_FONTCONVERTER` --- Build the @ref magnum-fontconverter "magnum-fontconverter" + executable for converting fonts of different formats. Enables also building + of the @ref Text library. Available only on desktop GL. Enables building of + one of the windowless application libraries based on the target platform. +- `WITH_IMAGECONVERTER` --- Build the @ref magnum-imageconverter "magnum-imageconverter" executable for converting images of different formats. Some of these utilities operate with plugins and they search for them in the -default plugin locations. You can override those locations using +default plugin locations. You can override these locations using the `MAGNUM_PLUGINS_DIR` and `MAGNUM_PLUGINS_[DEBUG|RELEASE]_DIR` variables, much like when using Magnum from dependent projects --- see @ref cmake for more information. In particular, if you specify them as relative paths, the path will be taken relative to executable location, which is useful for making relocatable installations. -Note that [each namespace](namespaces.html), all @ref Platform libraries and -the @ref OpenGLTester class contain more detailed information about -dependencies, availability on particular platform and also guide how to enable -given library in build and use it with CMake. +Note that each [namespace](namespaces.html) documentation, all @ref Platform +library documentation and the @ref OpenGLTester class documentation contain +more detailed information about dependencies, availability on particular +platform and also guide how to enable given library for building and how to use +it with CMake. -@subsection building-tests Building and running unit tests +This list covers only the core Magnum features, see also features offered by +@ref building-corrade-features "Corrade", +@ref building-plugins-features "Magnum Plugins", +@ref building-integration-features "Magnum Integration", +@ref building-extras-features "Magnum Extras" and +@ref building-examples-features "Magnum Examples". -If you want to build also unit tests (which are not built by default), enable -`BUILD_TESTS` in CMake. Unit tests use Corrade's @ref Corrade::TestSuite -"TestSuite" framework and can be run either manually (the binaries are located -in `Test/` subdirectories of build directory) or using +@subsection building-tests Building and running tests + +If you want to build also the tests (which are not built by default), enable +`BUILD_TESTS` in CMake. The tests use Corrade's +@ref Corrade::TestSuite "TestSuite" framework and can be run either manually +(the binaries are located in `Test/` subdirectories in the build directory) or +using @code{.sh} ctest --output-on-failure @endcode -in build directory. On Windows the tests require the library to be installed -with DLLs accessible through `PATH`. See -@ref building-windows "above Windows documentation" for more information. +in the build directory. On Windows the tests require the library to be +installed with DLLs accessible through @cb{.bat} %PATH% @ce. See the above +@ref building-windows "Windows documentation" for more information. The @ref Audio library has tests which require OpenAL to be able to create a -context. That is the case on most platforms, so they are enabled by default. +context. That is the case on most platforms, so they are enabled by default. In case it's not possible to have OpenAL context (such as when running @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten" tests under Node.js), you can disable building of them with `BUILD_AL_TESTS`. The tests are suffixed with @@ -327,86 +498,36 @@ running CTest, e.g.: ctest -R GLTest # run only tests requiring OpenGL context @endcode -@subsection building-doc Building documentation +@section building-doc Building documentation -The documentation (which you are currently reading) is written in **Doxygen** -and additionally uses **LaTeX** for math formulas. Documentation using the -stock HTML theme can be build by running +The documentation (which you are currently reading) is written in +[Doxygen](http://doxygen.org) and additionally uses **LaTeX** for math +formulas. Documentation using the stock HTML theme can be build by running @code{.sh} doxygen @endcode -in root directory (i.e. where `Doxyfile` is). Resulting HTML documentation -will be in `build/doc/` directory. You might need to create `build/` directory -if it doesn't exist yet. If Corrade with generated documentation is placed in -`corrade` directory next to `magnum`, the documentation will be crosslinked -with Corrade's one. If related projects (`magnum-plugins`, `magnum-extras`, -`magnum-integration` and `magnum-examples`, see below) are places along these, -their documentation will be also included in generated output. - -The documentation can be also generated using the [m.css Doxygen theme](http://mcss.mosra.cz/doxygen/). -Use `Doxyfile-mcss` for local build, the `Doxyfile-public` is meant for the -publicly available documentation at http://doc.magnum.graphics/magnum/. - -@section building-related Related projects - -The engine itself is kept as small as possible with only little dependencies. -Additional functionality, often depending on external libraries, is provided in -separate repositories. Various importer plugins for image, audio and 3D model -formats are maintained in @ref building-plugins "Plugins repository", -integration with various external math and physics libraries is provided by -@ref building-integration "Integration libraries" and other extra features are -in the @ref building-extras "Extra libraries". Various examples are provided -by the @ref building-examples "Examples repository". - -@section building-packages Prepared packages - -@subsection building-packages-arch ArchLinux packages - -In `package/archlinux` directory is currently one package for Git development -build. The package is also in AUR under the same name. - -There are also a few development PKGBUILDs in `package/archlinux`, which allow -you to build and install the package directly from source tree without -downloading anything. The native PKGBUILDs also contain @cb{.sh} check() @ce -function which will run all unit tests before packaging. - -@subsection building-packages-gentoo Gentoo ebuilds - -Gentoo Git ebuild is available in `package/gentoo` directory. - -@subsection building-packages-deb DEB packages - -There is also `package/debian/` directory with all files needed for building -Debian packages. You need to have `corrade-dev` DEB package installed and in -addition also `dpkg-dev` and `debhelper` packages. Building is easy, just -change directory to package root, link or copy `package/debian` directory there -and run `dpkg-buildpackage`: - -@code{.sh} -ln -s package/debian . -dpkg-buildpackage -@endcode - -This will compile binary and development packages, which will then appear in -parent directory. If you need to modify CMake flags (enabling/disabling some -features, for example), modify the last entry in `debian/rules`. - -@subsection building-packages-brew Homebrew formulas - -macOS Homebrew formulas are in `package/homebrew` directory. Either use the -`*.rb` files directly or use the tap at https://github.com/mosra/homebrew-magnum : - -@code{.sh} -brew install --HEAD mosra/magnum/magnum -@endcode +in the root directory (i.e. where `Doxyfile` is). The resulting HTML +documentation will be in the `build/doc/` directory. You might need to create +the `build/` directory if it doesn't exist yet. If Corrade with generated +documentation is placed in the `corrade` directory next to `magnum`, the +documentation will be crosslinked with Corrade's one. If related projects +(`magnum-plugins`, `magnum-extras`, `magnum-integration` and `magnum-examples`, +see below) are places along these, their documentation will be also included in +generated output. + +The documentation can be also generated using the +[m.css Doxygen theme](http://mcss.mosra.cz/doxygen/). Use `Doxyfile-mcss` for a +local build, the `Doxyfile-public` is meant for the publicly available +documentation at http://doc.magnum.graphics/magnum/. The resulting +documentation will be either in `build/doc-mcss/` or `build/doc-public/`. @section building-windows-angle Building for ANGLE on Windows -Magnum is able to run on ANGLE OpenGL-to-D3D translator. Download the code from -https://github.com/MSOpenTech/angle and use provided Visual Studio solution to -build it. Put the resulting `libGLESv2`/`libEGL` libraries and +Magnum is able to run on the ANGLE OpenGL-to-D3D translator. Download the code +from https://github.com/MSOpenTech/angle and use the provided Visual Studio +solution to build it. Put the resulting `libGLESv2`/`libEGL` libraries and `GLES2`/`GLES3`/`EGL` includes to a location where CMake can find them or set `CMAKE_PREFIX_PATH` accordingly. ANGLE supports only OpenGL ES, thus you need to enable `TARGET_GLES`. The engine is built for OpenGL ES 2.0 by default, @@ -422,42 +543,44 @@ cmake .. ^ cmake --build . @endcode -@section building-crosscompiling Crosscompiling +@section building-cross Cross-compiling -For crosscompiling you need to have *both* target and native version of +For cross-compiling you need to have *both* target and native version of Corrade installed, because Corrade needs to run `corrade-rc` utility on the host system as part of the build process. If native version of `corrade-rc` is -not found on the system, crosscompilation will fail. +not found on the system, cross-compilation will fail. You also need to have the toolchains submodule updated. Either run the -following commands, or, if you build from source archive, download snapshot of -toolchains repository from https://github.com/mosra/toolchains and put the -contents in `toolchains/` subdirectory. +following command, or, if you build from source archive, download a snapshot of +the toolchains repository from https://github.com/mosra/toolchains and put the +contents in the `toolchains/` subdirectory. @code{.sh} git submodule update --init @endcode Note that CMake for some reason treats `CMAKE_PREFIX_PATH` and -`CMAKE_INSTALL_PREFIX` differently while crosscompiling and you may need to add -dependency paths to both `CMAKE_PREFIX_PATH` and `CMAKE_FIND_ROOT_PATH` to make -it able to find the dependencies. +`CMAKE_INSTALL_PREFIX` differently while cross-compiling and you may need to +add dependency paths to both `CMAKE_PREFIX_PATH` and `CMAKE_FIND_ROOT_PATH` to +make it able to find the dependencies. -@subsection building-cross-winrt Crosscompiling for Windows RT +@subsection building-cross-winrt Cross-compiling for Windows RT -As said above, you need native build of `corrade-rc` executable. The below +As said above, you need a native build of the `corrade-rc` executable and +@ref building-corrade-cross-winrt "Corrade built for Windows RT". The below script assumes that native Corrade build is installed in `C:/Sys` and the installation path for WinRT dependencies is in `C:/Sys-winrt`. -You need at least Windows 8.1, Visual Studio 2013 and Windows 8.1 Store/Phone +You need at least Windows 8.1, Visual Studio 2015 and Windows 8.1 Store/Phone SDK installed. Windows RT applications support OpenGL only through ANGLE, which is currently limited to OpenGL ES. Download and build ANGLE -@ref building-windows-angle "according to instructions above", but use project -files from the `winrt/` directory instead. Version 2.0.4 of SDL has support for -WinRT applications, download the source from https://www.libsdl.org/download-2.0.php -and use project files from the `VisualC-WinRT` directory. Because WinRT -applications run in a sandbox, it's recommended to build the library as static -so you don't have to bundle all the DLLs. Example: +@ref building-windows-angle "according to the instructions above", but use +project files from the `winrt/` directory instead. Starting with version 2.0.4, +SDL has support for WinRT applications --- download the source from +https://www.libsdl.org/download-2.0.php and use project files from the +`VisualC-WinRT` directory. Because WinRT applications run in a sandbox, it's +recommended to build the library as static so you don't have to bundle all the +DLLs. Example: @code{.bat} mkdir build-winrt && cd build-winrt @@ -473,29 +596,29 @@ cmake --build . @endcode Change `WindowsStore` to `WindowsPhone` if you want to build for Windows Phone -instead. When done, you can install the package using `cmake --build . --target install` -to make it available for depending projects. +instead. When done, you can install the package using +@cb{.bat} cmake --build . --target install @ce to make it available to +depending projects. See @ref Platform::Sdl2Application documentation for more information about building your projects for WinRT. -@subsection building-cross-win Crosscompiling for Windows using MinGW-w64 +@subsection building-cross-win Cross-compiling for Windows using MinGW-w64 -@note This guide is tailored mainly for crosscompiling from ArchLinux. For - this system there is also prepared `mingw-w64-magnum` development package +@note This guide is tailored mainly for cross-compiling from ArchLinux. For + this system there is also a prepared `mingw-w64-magnum` development package in `package/archlinux`, named `PKGBUILD-mingw-w64`. See @ref building-packages-arch "above" for more information. -You will need MinGW-w64 versions of the compiler and all dependent libraries -(Corrade), i.e. these ArchLinux packages: +You will need a MinGW-w64 version of the compiler, i.e. the `mingw-w64-gcc` +ArchLinux package, and also +@ref building-corrade-cross-win "Corrade built for MinGW". -- `mingw-w64-gcc` -- `mingw-w64-corrade` - -Then create build directories for 32b/64b build and run cmake and build command -in them. You may need to modify the `basic-mingw-w64-32.cmake`/`basic-mingw-w64-64.cmake` -files and `CMAKE_INSTALL_PREFIX` to suit your distribution filesystem -hierarchy and specify path where Corrade is installed in `CMAKE_PREFIX_PATH`. +Create build directories for 32b/64b build and run `cmake` and the build +command in them. You may need to modify the `basic-mingw-w64-32.cmake` / +`basic-mingw-w64-64.cmake` files and `CMAKE_INSTALL_PREFIX` to suit your +distribution filesystem hierarchy and also specify path where Corrade is +installed in `CMAKE_PREFIX_PATH`. @code{.sh} mkdir build-mingw-w64-32 && cd build-mingw-w64-32 @@ -513,17 +636,19 @@ cmake .. \ cmake --build . @endcode -Then you can install the package using `cmake --build . --target install` to -make it available for depending projects. +Then you can install the package using @cb{.sh} cmake --build . --target install @ce +to make it available to depending projects. -@subsection building-cross-emscripten Crosscompiling for Emscripten +@subsection building-cross-emscripten Cross-compiling for Emscripten -You will need [Emscripten](http://kripken.github.io/emscripten-site/docs/getting_started/Tutorial.html) -installed and configured. The toolchains require CMake 3.7 or newer to properly -set compiler and linker flags. +You will need [Emscripten](http://kripken.github.io/emscripten-site/) installed +and configured and +@ref building-corrade-cross-emscripten "Corrade built for Emscripten". The +toolchains require CMake 3.7 or newer to properly set compiler and linker +flags. There are two toolchain files. The `generic/Emscripten.cmake` is for the -classical (asm.js) build, the `generic/Emscripten-wasm.cmake` is for +classical (asm.js) build, the `generic/Emscripten-wasm.cmake` is for a WebAssembly build. Don't forget to adapt `EMSCRIPTEN_PREFIX` variable in `generic/Emscripten*.cmake` to path where Emscripten is installed; you can also pass it explicitly on command-line using `-DEMSCRIPTEN_PREFIX`. Default is @@ -531,8 +656,9 @@ pass it explicitly on command-line using `-DEMSCRIPTEN_PREFIX`. Default is porting and they are generally slower, thus `BUILD_STATIC` is implicitly enabled. -Then create build directory and run cmake and build command in it. Be sure to -set `CMAKE_INSTALL_PREFIX` to path contained in `EMSCRIPTEN_TOOLCHAIN_PATH`. +Then create build directory and run `cmake` and the build command in it. Be +sure to set `CMAKE_INSTALL_PREFIX` to a path contained in +`EMSCRIPTEN_TOOLCHAIN_PATH`. WebGL 1.0 (GLES 2.0 equivalent) is enabled by default, switch to 2.0 (GLES 3.0 equivalent) by disabling `TARGET_GLES2`. @@ -548,11 +674,11 @@ cmake .. \ cmake --build . @endcode -Then you can install the library using `cmake --build . --target install` to -make it available for depending projects. +Then you can install the library using @cb{.sh} cmake --build . --target install @ce +to make it available to depending projects. If you have Node.js installed, you can also build and run unit tests using -`ctest`. See `BUILD_TESTS` above. +`ctest`. See the `BUILD_TESTS` option @ref building-tests "above". For ArchLinux there are also prepared package files in `package/archlinux`, named `PKGBUILD-emscripten`, `PKGBUILD-emscripten-webgl2`, @@ -565,13 +691,14 @@ unoptimized build (faster to compile) and the third for WebAssembly build. See @ref Platform::Sdl2Application documentation for more information about building your projects for Emscripten. -@subsection building-cross-ios Crosscompiling for iOS +@subsection building-cross-ios Cross-compiling for iOS -You will need macOS and Xcode installed. +You will need macOS with Xcode installed. -Set `CMAKE_OSX_ROOT` to SDK you want to target and enable all desired -architectures in `CMAKE_OSX_ARCHITECTURES`. Be sure to set `CMAKE_INSTALL_PREFIX` -to prefix where you store other iOS dependencies such as Corrade or SDL2. +Set `CMAKE_OSX_ROOT` to the SDK you want to target and enable all desired +architectures in `CMAKE_OSX_ARCHITECTURES`. Be sure to set +`CMAKE_INSTALL_PREFIX` to prefix where you store other iOS dependencies such as +@ref building-corrade-cross-ios "Corrade built for iOS" or a SDL2 iOS build. As every application is in its own sandbox, it doesn't make sense to build shared libraries (although it is supported). Enable `BUILD_STATIC` to build @@ -590,32 +717,33 @@ cmake .. \ -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk \ -DCMAKE_OSX_ARCHITECTURES="arm64;armv7;armv7s" \ -DCMAKE_INSTALL_PREFIX=~/ios-libs \ - -DBUILD_STATIC=ON -DBUILD_PLUGINS_STATIC=ON \ + -DBUILD_STATIC=ON \ + -DBUILD_PLUGINS_STATIC=ON \ -DTARGET_GLES2=OFF \ -DWITH_SDL2APPLICATION=ON \ -G Xcode cmake --build . @endcode -Then you can install the library using `cmake --build . --target install` to -make it available for depending projects. +Then you can install the library using @cb{.sh} cmake --build . --target install @ce +to make it available to depending projects. See @ref Platform::Sdl2Application documentation for more information about building your projects for iOS. -@subsection building-cross-android Crosscompiling for Android ARM and x86 +@subsection building-cross-android Cross-compiling for Android ARM and x86 You will need [Android NDK](https://developer.android.com/tools/sdk/ndk/index.html) -installed and configured. +installed and configured and @ref building-corrade-cross-android "Corrade built for Android". -Don't forget to adapt `ANDROID_NDK_ROOT` in `generic/Android-*.cmake` to path +Don't forget to adapt `ANDROID_NDK_ROOT` in `generic/Android-*.cmake` to a path where NDK is installed. Default is `/opt/android-ndk`. Adapt also `ANDROID_SYSROOT` to your preferred API level. You might also need to update `ANDROID_TOOLCHAIN_PREFIX` and `ANDROID_TOOLCHAIN_ROOT` to fit your system. -Then create build directory and run cmake and build command in it. Be sure to -set `CMAKE_INSTALL_PREFIX` to `/usr` subdirectory of `ANDROID_SYSROOT` and -specify path where Corrade is installed in `CMAKE_PREFIX_PATH`. +Then create a build directory and run `cmake` and the build command in it. Be +sure to set `CMAKE_INSTALL_PREFIX` to `/usr` subdirectory of `ANDROID_SYSROOT` +and specify path where Corrade is installed in `CMAKE_PREFIX_PATH`. Note that `BUILD_STATIC` is implicitly enabled, because manually loading all depending shared libraries using JNI would be too inconvenient. The engine is @@ -645,13 +773,26 @@ cmake .. \ cmake --build . @endcode -Then you can install the library using `cmake --build . --target install` to -make it available for depending projects. +Then you can install the library using @cb{.sh} cmake --build . --target install @ce +to make it available to depending projects. For ArchLinux there are also prepared package files in `package/archlinux`, named `PKGBUILD-android-arm` and `PKGBUILD-android-x86`, see @ref building-packages-arch "above" for more information. +@attention + On Windows it's possible that you get the following CMake error when + configuring the project: +@attention +
+ CMAKE_SYSTEM_NAME is 'Android' but 'NVIDIA Nsight Tegra Visual Studio + Edition' is not installed. +
+@attention + This is because MSVC as the default generator on Windows is not able to + build arbitrary Android projects. To fix it, use a different generator (for + example Ninja, by passing `-G Ninja` to CMake). + See @ref Platform::AndroidApplication documentation for more information about building your projects for Android. @@ -659,11 +800,11 @@ building your projects for Android. @subsection building-ci-travis Travis -In `package/ci/` there is a `travis.yml` file with Linux GCC 4.7, macOS Clang, -Linux desktop GLES2/GLES3, iOS GLES2/GLES3, Emscripten WebGL1/WebGL2, -Android GLES2/GLES3, AddressSanitizer and ThreadSanitizer configuration. Online -at https://travis-ci.org/mosra/magnum. The Linux build has code coverage -reports available online at https://coveralls.io/github/mosra/magnum. +In `package/ci/` there is a `travis.yml` file with Linux GCC 4.7, macOS, Linux +desktop GLES2/GLES3, iOS GLES2/GLES3, Emscripten WebGL1/WebGL2, Android +GLES2/GLES3, AddressSanitizer and ThreadSanitizer configuration. Online at +https://travis-ci.org/mosra/magnum. The Linux build has code coverage reports +available online at https://coveralls.io/github/mosra/magnum. @subsection building-ci-appveyor AppVeyor diff --git a/doc/getting-started.dox b/doc/getting-started.dox index 73ba4b75b..9de065846 100644 --- a/doc/getting-started.dox +++ b/doc/getting-started.dox @@ -33,7 +33,7 @@ Setting up a new project can be pretty gruesome and nobody likes repeating the same process every time. Magnum provides "bootstrap" project structures for many use cases, helping you get up and running in no time. -@section getting-started-bootstrap Download a bootstrap project +@section getting-started-bootstrap Download the bootstrap project The [bootstrap repository](https://github.com/mosra/magnum-bootstrap) is located on GitHub. The `master` branch contains just a README file and the @@ -47,8 +47,16 @@ better to init your new project from scratch with clean Git history. @section getting-started-download Download, build and install Corrade and Magnum Magnum libraries support both separate compilation/installation and CMake -subprojects. We'll use the subproject approach now --- adding the dependencies -means just cloning them into your project tree: +subprojects. If you are lucky, you may already have Magnum packages ready for +your platform and you can skip the rest of this section: + +- @ref building-packages-arch +- @ref building-packages-deb +- @ref building-packages-gentoo +- @ref building-packages-brew + +If you don't, don't worry, let's use the subproject approach instead. Adding +the dependencies means just cloning them into your project tree: @code{.sh} cd /path/to/the/extracted/bootstrap/project @@ -71,14 +79,15 @@ add_subdirectory(magnum) add_subdirectory(src) @endcode -@note In the long run it's better to install Corrade and Magnum separately - instead of cloning them into your project tree, as that can vastly improve +@note + In the long run it's better to install Corrade and Magnum separately + instead of cloning them into your project tree, as that vastly improves your iteration times. Follow @ref building "the full installation guide" if you want to go that route; don't forget to enable `WITH_SDL2APPLICATION` when building Magnum so the bootstrap project can use it later. There are also ready-to-use packages for various OSes and distributions. - -@note If you have that, you don't need to clone the subprojects and modify the +@note + If you have that, you don't need to clone the subprojects and modify the `CMakeLists.txt` file like above, you might only need to set `CMAKE_PREFIX_PATH` if you installed Corrade and Magnum to a non-standard location. diff --git a/doc/mainpage.dox b/doc/mainpage.dox index bb565b3b2..1288492b6 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -32,69 +32,14 @@ This is a documentation for the Magnum Project. To see high-level feature overview, project goals or read the developer blog, head over to the [project homepage](http://magnum.graphics/). -@section mainpage-building Building Magnum - -You can either use packaging scripts, which are stored in the `package/` -subdirectory [of the Git repository](https://github.com/mosra/magnum/tree/master/package), -or compile and install everything manually. A short guide is below, for better -introduction it's advised to read through the -@ref getting-started "Getting Started Guide". Complete building documentation -covering all platforms and feature sets is in the @ref building page. - -@subsection mainpage-building-dependencies Minimal dependencies - -- C++ compiler with good C++11 support. Compilers which are tested to have - everything needed are **GCC** >= 4.7, **Clang** >= 3.1 and **MSVC** >= 2015. - On Windows you can also use **MinGW-w64**. -- **CMake** >= 2.8.12 -- **Corrade** - Plugin management and utility library. See how to get it at - http://doc.magnum.graphics/corrade/. - -@subsection mainpage-building-compilation Compilation, installation - -The library (for example with support for SDL2 applications) can be built and -installed using these commands: - -@code{.sh} -git clone git://github.com/mosra/magnum && cd magnum -mkdir -p build && cd build -cmake .. \ - -DCMAKE_INSTALL_PREFIX=/usr \ - -DWITH_SDL2APPLICATION=ON -make -j -make install # sudo may be required -@endcode - -@subsection mainpage-building-tests Building and running unit tests - -If you want to build also unit tests (which are not built by default), pass -`-DBUILD_TESTS=ON` to CMake. Unit tests use Corrade's @ref Corrade::TestSuite "TestSuite" -framework and can be run using - -@code{.sh} -ctest --output-on-failure -@endcode - -in build directory. Everything should pass ;) - -@subsection mainpage-building-doc Building documentation - -The documentation, which you are currently reading, is written using -[Doxygen](https://doxygen.org). It can be build by running - -@code{.sh} -doxygen -@endcode - -in the root directory (i.e. where `Doxyfile` is). You may need to create the -`build/` directory if it doesn't exist yet. Resulting HTML documentation will -be in the `build/doc/` directory. - @section mainpage-getting-started Getting started The best way to get started is to read the thorough @ref getting-started "guide to download, build, install and start using Magnum" -in your project. After that, there are various @ref example-index "tutorials and examples" +in your project. There is also a complete @ref building documentation --- we +provide ready-made packages for many platforms. + +After that, there are various @ref example-index "tutorials and examples" and a complete @ref features "feature guide" explaining all aspects of the library. diff --git a/doc/namespaces.dox b/doc/namespaces.dox index 319f48bc7..2a5c98914 100644 --- a/doc/namespaces.dox +++ b/doc/namespaces.dox @@ -32,8 +32,17 @@ Contains classes for interacting with OpenGL. All of this library except @ref OpenGLTester is built as part of Magnum by -default. To use it, you need to find `Magnum` package and link to `Magnum::Magnum` -target. See @ref building and @ref cmake for more information. +default. To use this library with CMake, you need to request the `Magnum` +package and link to the `Magnum::Magnum` target: + +@code{.cmake} +find_package(Magnum REQUIRED) + +# ... +target_link_libraries(your-app Magnum::Magnum) +@endcode + +See @ref building and @ref cmake for more information. */ /** @dir Magnum/Platform @@ -46,11 +55,20 @@ Base classes for creating applications with various toolkits. 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 and link to -`Magnum::*Application` target. See particular `*Application` class -documentation, @ref building, @ref cmake and @ref platform for more -information. +platform requirements. To use a particular application library with CMake, you +need to request given `*Application` component of the `Magnum` package and link +to the `Magnum::Application` target. Example using the @ref Platform::Sdl2Application +library: + +@code{.cmake} +find_package(Magnum REQUIRED Sdl2Application) + +# ... +target_link_libraries(your-app Magnum::Application) +@endcode + +See documentation of particular `*Application` classs, @ref building, +@ref cmake and @ref platform for more information. */ /** @dir Magnum/Math @@ -61,18 +79,37 @@ information. Template classes for matrix and vector calculations. -This library is built as part of Magnum by default. To use it, you need to -find `Magnum` package and link to `Magnum::Magnum` target. 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 this library with +CMake, you need to find the `Magnum` package and link to the `Magnum::Magnum` +target: + +@code{.cmake} +find_package(Magnum REQUIRED) + +# ... +target_link_libraries(your-app Magnum::Magnum) +@endcode + +See @ref building, @ref cmake, @ref matrix-vector and @ref transformations for +more information. */ /** @namespace Magnum::Math::Literals @brief Math literals Literals for easy construction of angle and color values. -This library is built as part of Magnum by default. To use it, you need to -find `Magnum` package and link to `Magnum::Magnum` target. See @ref building -and @ref cmake for more information. +This library is built as part of Magnum by default. To use this library with +CMake, you need to find the `Magnum` package and link to the `Magnum::Magnum` +target: + +@code{.cmake} +find_package(Magnum REQUIRED) + +# ... +target_link_libraries(your-app Magnum::Magnum) +@endcode + +See @ref building, @ref cmake and @ref types for more information. */ /** @dir Magnum/Math/Algorithms @@ -83,9 +120,18 @@ and @ref cmake for more information. Various matrix and vector algorithms. -This library is built as part of Magnum by default. To use it, you need to -find `Magnum` package and link to `Magnum::Magnum` target. See @ref building -and @ref cmake for more information. +This library is built as part of Magnum by default. To use this library with +CMake, you need to find the `Magnum` package and link to the `Magnum::Magnum` +target: + +@code{.cmake} +find_package(Magnum REQUIRED) + +# ... +target_link_libraries(your-app Magnum::Magnum) +@endcode + +See @ref building and @ref cmake for more information. */ /** @dir Magnum/Math/Geometry @@ -94,25 +140,52 @@ and @ref cmake for more information. /** @namespace Magnum::Math::Geometry @brief Geometry library -This library is built as part of Magnum by default. To use it, you need to -find `Magnum` package and link to `Magnum::Magnum` target. See @ref building -and @ref cmake for more information. +This library is built as part of Magnum by default. To use this library with +CMake, you need to find the `Magnum` package and link to the `Magnum::Magnum` +target: + +@code{.cmake} +find_package(Magnum REQUIRED) + +# ... +target_link_libraries(your-app Magnum::Magnum) +@endcode + +See @ref building and @ref cmake for more information. */ /** @namespace Magnum::Math::Geometry::Distance @brief Functions for calculating distances -This library is built as part of Magnum by default. To use it, you need to -find `Magnum` package and link to `Magnum::Magnum` target. See @ref building -and @ref cmake for more information. +This library is built as part of Magnum by default. To use this library with +CMake, you need to find the `Magnum` package and link to the `Magnum::Magnum` +target: + +@code{.cmake} +find_package(Magnum REQUIRED) + +# ... +target_link_libraries(your-app Magnum::Magnum) +@endcode + +See @ref building and @ref cmake for more information. */ /** @namespace Magnum::Math::Geometry::Intersection @brief Function for calculating intersections -This library is built as part of Magnum by default. To use it, you need to -find `Magnum` package and link to `Magnum::Magnum` target. See @ref building -and @ref cmake for more information. +This library is built as part of Magnum by default. To use this library with +CMake, you need to find the `Magnum` package and link to the `Magnum::Magnum` +target: + +@code{.cmake} +find_package(Magnum REQUIRED) + +# ... +target_link_libraries(your-app Magnum::Magnum) +@endcode + +See @ref building and @ref cmake for more information. */ /** @dir Magnum/Audio @@ -123,13 +196,23 @@ and @ref cmake for more information. Audio import, playback and integration with @ref SceneGraph. -This library depends on **OpenAL** library. It is built if `WITH_AUDIO` is -enabled when building Magnum. To use this library, you need to request -`Audio` component of `Magnum` package in CMake and link to -`Magnum::Audio` target. See @ref building and @ref cmake for more information. -Additional plugins are enabled separately, see particular `Audio::*Importer` -class documentation, @ref building-plugins, @ref cmake-plugins and @ref plugins -for more information. +This library depends on the [OpenAL](https://www.openal.org/) library. It is +built if `WITH_AUDIO` is enabled when building Magnum. To use this library with +CMake, you need to request the `Audio` component of the `Magnum` package and +link to the `Magnum::Audio` target: + +@code{.cmake} +find_package(Magnum REQUIRED Audio) + +# ... +target_link_libraries(your-app Magnum::Audio) +@endcode + +See @ref building and @ref cmake for more information. + +Additional plugins are built separately, see particular `Audio::*Importer` +class documentation, @ref building, @ref building-plugins, @ref cmake, +@ref cmake-plugins and @ref plugins for more information. */ /** @dir Magnum/DebugTools @@ -141,9 +224,17 @@ for more information. Debugging helpers, renderers and profilers. 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` target. See @ref building, -@ref cmake and @ref debug-tools for more information. +use this library with CMake, you need to request the `DebugTools` component of +the `Magnum` package and link to the `Magnum::DebugTools` target: + +@code{.cmake} +find_package(Magnum REQUIRED DebugTools) + +# ... +target_link_libraries(your-app Magnum::DebugTools) +@endcode + +See @ref building, @ref cmake and @ref debug-tools for more information. */ /** @dir Magnum/MeshTools @@ -155,9 +246,17 @@ package in CMake and link to `Magnum::DebugTools` target. See @ref building, Tools for generating, optimizing and cleaning meshes. 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` target. See @ref building and -@ref cmake for more information. +use this library with CMake, you need to request the `MeshTools` component of +the `Magnum` package and link to `Magnum::MeshTools` target: + +@code{.cmake} +find_package(Magnum REQUIRED MeshTools) + +# ... +target_link_libraries(your-app Magnum::MeshTools) +@endcode + +See @ref building and @ref cmake for more information. */ /** @dir Magnum/Primitives @@ -169,9 +268,17 @@ package in CMake and link to `Magnum::MeshTools` target. See @ref building and Basic primitives for testing purposes. 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` target. See @ref building and -@ref cmake for more information. +use this library with CMake, you need to request the `Primitives` component of +the `Magnum` package and link to the `Magnum::Primitives` target: + +@code{.cmake} +find_package(Magnum REQUIRED Primitives) + +# ... +target_link_libraries(your-app Magnum::Primitives) +@endcode + +See @ref building and @ref cmake for more information. */ /** @dir Magnum/SceneGraph @@ -183,9 +290,17 @@ package in CMake and link to `Magnum::Primitives` target. See @ref building and Managing object hierarchy, transformations and interactions. 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` target. See @ref building, -@ref cmake and @ref scenegraph for more information. +use this library with CMake, you need to request the `SceneGraph` component of +the `Magnum` package and link to `Magnum::SceneGraph` target: + +@code{.cmake} +find_package(Magnum REQUIRED SceneGraph) + +# ... +target_link_libraries(your-app Magnum::SceneGraph) +@endcode + +See @ref building, @ref cmake and @ref scenegraph for more information. */ /** @dir Magnum/Shaders @@ -197,9 +312,17 @@ package in CMake and link to `Magnum::SceneGraph` target. See @ref building, Collection of shaders for easy prototyping and basic usage. 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::Shaders` target. See @ref building, @ref cmake -and @ref shaders for more information. +use this library with CMake, you need to request the `Shaders` component of the +`Magnum` package and link to the `Magnum::Shaders` target: + +@code{.cmake} +find_package(Magnum REQUIRED Shaders) + +# ... +target_link_libraries(your-app Magnum::Shaders) +@endcode + +See @ref building, @ref cmake and @ref shaders for more information. */ /** @dir Magnum/Shapes @@ -211,9 +334,17 @@ and @ref shaders for more information. Collision detection system. 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` target. See @ref building, @ref cmake and -@ref shapes for more information. +this library with CMake, you need to request the `Shapes` component of the +`Magnum` package and link to the `Magnum::Shapes` target: + +@code{.cmake} +find_package(Magnum REQUIRED Shapes) + +# ... +target_link_libraries(your-app Magnum::Shapes) +@endcode + +See @ref building, @ref cmake and @ref shapes for more information. */ /** @dir Magnum/Text @@ -225,11 +356,21 @@ CMake and link to `Magnum::Shapes` target. See @ref building, @ref cmake and Font texture creation and text layouting. 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` target. 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. +this library with CMake, you need to request the `Text` component of the +`Magnum` package and link to the `Magnum::Text` target: + +@code{.cmake} +find_package(Magnum REQUIRED Text) + +# ... +target_link_libraries(your-app Magnum::Text) +@endcode + +See @ref building and @ref cmake for more information. + +Additional plugins are built separately, see particular `*Font` and +`*FontConverter` class documentation, @ref building, @ref building-plugins, +@ref cmake, @ref cmake-plugins and @ref plugins for more information. */ /** @dir Magnum/TextureTools @@ -241,9 +382,18 @@ more information. Additional plugins are enabled separately, see particular Tools for generating, compressing and optimizing textures. 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`. See @ref building and -@ref cmake for more information. +To use this library with CMake, you need to request the `TextureTools` +component of the `Magnum` package in CMake and link to the +`Magnum::TextureTools` target: + +@code{.cmake} +find_package(Magnum REQUIRED TextureTools) + +# ... +target_link_libraries(your-app Magnum::TextureTools) +@endcode + +See @ref building and @ref cmake for more information. */ /** @dir Magnum/Trade @@ -256,10 +406,20 @@ Contains plugin interfaces for importing data of various formats and classes for direct access to the data. This library is built as part of Magnum by default. To use it, you need to -find `Magnum` package and link to `Magnum::Magnum` target. See @ref building -and @ref cmake for more information. Additional plugins are enabled separately, -see particular `Trade::*Importer` and `*ImageConverter` class documentation, -@ref building-plugins, @ref cmake-plugins and @ref plugins for more +find the `Magnum` package and link to the `Magnum::Magnum` target: + +@code{.cmake} +find_package(Magnum REQUIRED) + +# ... +target_link_libraries(your-app Magnum::Trade) +@endcode + +See @ref building and @ref cmake for more information. + +Additional plugins are built separately, see particular `Trade::*Importer` and +`*ImageConverter` class documentation, @ref building, @ref building-plugins, +@ref cmake, @ref cmake-plugins and @ref plugins for more information. */ diff --git a/src/Magnum/Audio/Extensions.h b/src/Magnum/Audio/Extensions.h index c08121ea7..8252a61cf 100644 --- a/src/Magnum/Audio/Extensions.h +++ b/src/Magnum/Audio/Extensions.h @@ -48,13 +48,18 @@ but these structs are better suited for compile-time decisions rather than @ref Extension instances. See @ref Context::isExtensionSupported() for example usage. -This namespace is not built by default. It is built if `WITH_AUDIO` is -enabled when building Magnum. To use this library, you need to request -`Audio` component of `Magnum` package in CMake and link to `Magnum::Audio` -target. 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. +This namespace is built if `WITH_AUDIO` is enabled when building Magnum. To use +this library with CMake, you need to request the `Audio` component of the +`Magnum` package and link to the `Magnum::Audio` target. + +@code{.cmake} +find_package(Magnum REQUIRED Audio) + +# ... +target_link_libraries(your-app Magnum::Audio) +@endcode + +See @ref building and @ref cmake for more information. @see @ref MAGNUM_ASSERT_AUDIO_EXTENSION_SUPPORTED() @todo Manual indices for extensions, this has gaps */ diff --git a/src/Magnum/Extensions.h b/src/Magnum/Extensions.h index 33526d97e..8a17046e8 100644 --- a/src/Magnum/Extensions.h +++ b/src/Magnum/Extensions.h @@ -58,8 +58,17 @@ but these structs are better suited for compile-time decisions rather than @ref Extension instances. See @ref Context::isExtensionSupported() for example usage. -This namespace is built by default. To use it, you need to link to -`Magnum::Magnum` target. See @ref building and @ref cmake for more information. +This library is built by default. To use this library with CMake, you need to +find the `Magnum` package and link to the `Magnum::Magnum` target: + +@code{.cmake} +find_package(Magnum REQUIRED) + +# ... +target_link_libraries(your-app Magnum::Magnum) +@endcode + +See @ref building and @ref cmake for more information. @see @ref MAGNUM_ASSERT_EXTENSION_SUPPORTED() @todo Manual indices for extensions, this has gaps */ diff --git a/src/Magnum/OpenGLTester.h b/src/Magnum/OpenGLTester.h index 9fb3b5e8d..d924e1e64 100644 --- a/src/Magnum/OpenGLTester.h +++ b/src/Magnum/OpenGLTester.h @@ -70,13 +70,22 @@ This class is available only on platforms with corresponding platforms except @ref CORRADE_TARGET_ANDROID "Android" and @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten". It is built into a separate static library and only if `WITH_OPENGLTESTER` is enabled when building Magnum. To use -it, you need to request `OpenGLTester` component of `Magnum` package in CMake, -derive your test class from this class instead of @ref Corrade::TestSuite::Tester -and either link to `Magnum::OpenGLTester` target or add it to `LIBRARIES` -section of the @ref corrade-cmake-add-test "corrade_add_test()" macro. See -@ref building and @ref cmake for more information. +it with CMake, you need to request the `OpenGLTester` component of the `Magnum` +package. Derive your test class from this class instead of +@ref Corrade::TestSuite::Tester and either link to `Magnum::OpenGLTester` +target or add it to the `LIBRARIES` section of the +@ref corrade-cmake-add-test "corrade_add_test()" macro: -## OpenGL context creation +@code{.cmake} +find_package(Magnum REQUIRED OpenGLTester) + +# ... +corrade_add_test(YourTest YourTest.cpp LIBRARIES Magnum::OpenGLTester) +@endcode + +See @ref building, @ref cmake and @ref testsuite for more information. + +@section OpenGLTester-context OpenGL context creation Upon construction the class creates an OpenGL context, meaning you don't have to worry about OpenGL context being available during the tests. If the context @@ -87,7 +96,7 @@ misuses will propagate to following test cases. See @ref TestSuite-Tester-command-line "command-line option overview" for a way to run single isolated test cases. -## Debug context and error checking +@section OpenGLTester-debug Debug context and error checking On platforms that support it, the OpenGL context is created with synchronous debug output, meaning that every OpenGL error is directly reported to standard @@ -96,7 +105,7 @@ upon encountering a GL error -- this should be done explicitly with @ref MAGNUM_VERIFY_NO_ERROR() instead, as the debug output is not available on all platforms and not all GL errors are fatal. -## GPU time benchmarks +@section OpenGLTester-benchmarks GPU time benchmarks This class adds @ref BenchmarkType::GpuTime to the benchmark type enum, allowing you to measure time spent on GPU as opposed to CPU or wall clock time. @@ -227,7 +236,8 @@ class OpenGLTester: public TestSuite::Tester { @brief Verify that no OpenGL error occurred Equivalent to -@code + +@code{.cpp} CORRADE_COMPARE(Magnum::Renderer::error(), Magnum::Renderer::Error::NoError) @endcode */ diff --git a/src/Magnum/Platform/AbstractXApplication.h b/src/Magnum/Platform/AbstractXApplication.h index 13ced8ee6..a34a756e1 100644 --- a/src/Magnum/Platform/AbstractXApplication.h +++ b/src/Magnum/Platform/AbstractXApplication.h @@ -56,8 +56,8 @@ namespace Implementation { Supports keyboard and mouse handling. See @ref platform for brief introduction. -@note Not meant to be used directly, see @ref GlxApplication and - @ref XEglApplication subclasses. +@note Not meant to be used directly, see the @ref GlxApplication and + @ref XEglApplication subclasses instead. */ class AbstractXApplication { public: diff --git a/src/Magnum/Platform/AndroidApplication.h b/src/Magnum/Platform/AndroidApplication.h index 9fcfe77b4..ff9b07789 100644 --- a/src/Magnum/Platform/AndroidApplication.h +++ b/src/Magnum/Platform/AndroidApplication.h @@ -50,13 +50,12 @@ namespace Magnum { namespace Platform { /** @nosubgrouping @brief Android application -Application running in Android. +Application running on Android. -This application library is available only in +This application library is available only on @ref CORRADE_TARGET_ANDROID "Android", see respective sections -in @ref building-corrade-cross-android "Corrade's" and @ref building-cross-android "Magnum's" -building documentation. It is built if `WITH_ANDROIDAPPLICATION` is enabled in -CMake. +in the @ref building-corrade-cross-android "Corrade" and +@ref building-cross-android "Magnum" building documentation. It is built if `WITH_ANDROIDAPPLICATION` is enabled when building Magnum. @section Platform-AndroidApplication-bootstrap Bootstrap application @@ -115,16 +114,31 @@ adb install bin/NativeActivity-debug.apk @section Platform-AndroidApplication-usage General usage -For CMake you need to copy `FindEGL.cmake` and `FindOpenGLES2.cmake` (or -`FindOpenGLES3.cmake`) from `modules/` directory in Magnum source to `modules/` -dir in your project (so it is able to find EGL and OpenGL ES libraries). -Request `AndroidApplication` component of `Magnum` package and link to -`Magnum::AndroidApplication` target. If no other application is requested, you -can also use generic `Magnum::Application` alias to simplify porting. Again, -see @ref building and @ref cmake for more information. Note that unlike on -other platforms you need to create *shared library* instead of executable. The -resulting binary then needs to be copied to `lib/armeabi-v7a` and `lib/x86`, -you can do that automatically in CMake using the following commands: +In order to use this library from CMake, you need to copy `FindEGL.cmake` +and `FindOpenGLES2.cmake` (or `FindOpenGLES3.cmake`) from the `modules/` +directory in Magnum source to the `modules/` dir in your project (so it is able +to find EGL and OpenGL ES libraries). Request the `AndroidApplication` +component of the `Magnum` package and link to the `Magnum::AndroidApplication` +target: + +@code{.cmake} +find_package(Magnum REQUIRED) +if(CORRADE_TARGET_ANDROID) + find_package(Magnum REQUIRED AndroidApplication) +endif() + +# ... +if(CORRADE_TARGET_ANDROID) + target_link_libraries(your-app Magnum::AndroidApplication) +endif() +@endcode + +If no other application is requested, you can also use the generic +`Magnum::Application` alias to simplify porting. Again, see @ref building and +@ref cmake for more information. Note that unlike on other platforms you need +to create *shared library* instead of executable. The resulting binary then +needs to be copied to `lib/armeabi-v7a` and `lib/x86`, you can do that +automatically in CMake using the following commands: @code{.cmake} file(MAKE_DIRECTORY "${CMAKE_SOURCE_DIR}/libs/${ANDROID_ABI}") diff --git a/src/Magnum/Platform/GlfwApplication.h b/src/Magnum/Platform/GlfwApplication.h index 712efda2a..ebee94082 100644 --- a/src/Magnum/Platform/GlfwApplication.h +++ b/src/Magnum/Platform/GlfwApplication.h @@ -49,12 +49,12 @@ namespace Magnum { namespace Platform { /** @nosubgrouping @brief GLFW application -Application using GLFW toolkit. Supports keyboard and mouse handling with -support for changing cursor and mouse tracking and warping. +Application using the [GLFW](http://glfw.org) toolkit. Supports keyboard and +mouse handling with support for changing cursor and mouse tracking and warping. This application library is available on all platforms where GLFW is ported. It -depends on **GLFW** library and is built if `WITH_GLFWAPPLICATION` is enabled -in CMake. +depends on the [GLFW](http://glfw.org) library and is built if +`WITH_GLFWAPPLICATION` is enabled when building Magnum. @section Platform-GlfwApplication-bootstrap Bootstrap application @@ -77,10 +77,22 @@ See @ref cmake for more information. @section Platform-GlfwApplication-usage General usage -In CMake you need to request `GlfwApplication` component of `Magnum` package -and link to `Magnum::GlfwApplication` target. If no other application is -requested, you can also use generic `Magnum::Application` alias to simplify -porting. Again, see @ref building and @ref cmake for more information. +In order to use this library from CMake, you need to copy `FindGLFW.cmake` from +the modules directory in Magnum source to the `modules/` dir in your project +(so it is able to find the GLFW library). Request the `GlfwApplication` +component of the `Magnum` package and link to the `Magnum::GlfwApplication` +target: + +@code{.cmake} +find_package(Magnum REQUIRED GlfwApplication) + +# ... +target_link_libraries(your-app Magnum::GlfwApplication) +@endcode + +If no other application is requested, you can also use the generic +`Magnum::Application` alias to simplify porting. Again, see @ref building and +@ref cmake for more information. In C++ code you need to implement at least @ref drawEvent() to be able to draw on the screen. The subclass can be then used directly in @cpp main() @ce diff --git a/src/Magnum/Platform/GlutApplication.h b/src/Magnum/Platform/GlutApplication.h index da481a844..eeb4d46fc 100644 --- a/src/Magnum/Platform/GlutApplication.h +++ b/src/Magnum/Platform/GlutApplication.h @@ -46,12 +46,13 @@ namespace Magnum { namespace Platform { /** @nosubgrouping @brief GLUT application -Application using GLUT toolkit. Supports keyboard and mouse handling with -support for changing cursor and mouse tracking and warping. +Application using the [GLUT](http://freeglut.sourceforge.net/) toolkit. +Supports keyboard and mouse handling with support for changing cursor and mouse +tracking and warping. This application library is available only on desktop OpenGL (Linux, Windows, -macOS). It depends on **GLUT** library and is built if `WITH_GLUTAPPLICATION` -is enabled in CMake. +macOS). It depends on the [GLUT](http://freeglut.sourceforge.net/) library and +is built if `WITH_GLUTAPPLICATION` is enabled when building Magnum. @section Platform-GlutApplication-bootstrap Bootstrap application @@ -74,10 +75,20 @@ See @ref cmake for more information. @section Platform-GlutApplication-usage General usage -In CMake you need to request `GlutApplication` component of `Magnum` package -and link to `Magnum::GlutApplication` target. If no other application is -requested, you can also use generic `Magnum::Application` alias to simplify -porting. Again, see @ref building and @ref cmake for more information. +In order to use this library from CMake, you need to request the +`GlutApplication` component of the `Magnum` package and link to the +`Magnum::GlutApplication` target: + +@code{.cmake} +find_package(Magnum REQUIRED GlutApplication) + +# ... +target_link_libraries(your-app Magnum::GlutApplication) +@endcode + +If no other application is requested, you can also use the generic +`Magnum::Application` alias to simplify porting. Again, see @ref building and +@ref cmake for more information. In C++ code you need to implement at least @ref drawEvent() to be able to draw on the screen. The subclass can be then used directly in @cpp main() @ce diff --git a/src/Magnum/Platform/GlxApplication.h b/src/Magnum/Platform/GlxApplication.h index 90fe9c7c8..75effcc15 100644 --- a/src/Magnum/Platform/GlxApplication.h +++ b/src/Magnum/Platform/GlxApplication.h @@ -41,8 +41,8 @@ Application using pure X11 and GLX. Supports keyboard and mouse handling. This application library is available on desktop OpenGL and @ref MAGNUM_TARGET_DESKTOP_GLES "OpenGL ES emulation on desktop" on Linux. It -depends on **X11** library and is built if `WITH_GLXAPPLICATION` is enabled in -CMake. +depends on the **X11** library and is built if `WITH_GLXAPPLICATION` is enabled +in CMake. @section Platform-GlxApplication-bootstrap Bootstrap application @@ -52,10 +52,20 @@ more information. @section Platform-GlxApplication-usage General usage -In CMake you need to request `GlxApplication` component of `Magnum` package and -link to `Magnum::GlxApplication` target. If no other application is requested, -you can also use generic `Magnum::Application` alias to simplify porting. See -@ref building and @ref cmake for more information. +In order to use this library from Cmake, you need to request the +`GlxApplication` component of the `Magnum` package and link to the +`Magnum::GlxApplication` target: + +@code{.cmake} +find_package(Magnum REQUIRED GlxApplication) + +# ... +target_link_libraries(your-app Magnum::GlxApplication) +@endcode + +If no other application is requested, you can also use the generic +`Magnum::Application` alias to simplify porting. See @ref building and +@ref cmake for more information. In C++ code you need to implement at least @ref drawEvent() to be able to draw on the screen. The subclass can be then used directly in @cpp main() @ce diff --git a/src/Magnum/Platform/Sdl2Application.h b/src/Magnum/Platform/Sdl2Application.h index 66dfa7ee6..ae400d1e7 100644 --- a/src/Magnum/Platform/Sdl2Application.h +++ b/src/Magnum/Platform/Sdl2Application.h @@ -62,8 +62,8 @@ This application library is in theory available for all platforms for which SDL2 is ported (thus also @ref CORRADE_TARGET_EMSCRIPTEN "Emscripten", see respective sections in @ref building-corrade-cross-emscripten "Corrade's" and @ref building-cross-emscripten "Magnum's" building documentation). It depends -on **SDL2** library (Emscripten has it built in) and is built if -`WITH_SDL2APPLICATION` is enabled in CMake. +on the [SDL2](http://www.libsdl.org) library (Emscripten has it built in) and +is built if `WITH_SDL2APPLICATION` is enabled in CMake. @section Platform-Sdl2Application-bootstrap Bootstrap application @@ -183,13 +183,23 @@ final package along with a PowerShell script for easy local installation. @section Platform-Sdl2Application-usage General usage -For CMake you need to copy `FindSDL2.cmake` from `modules/` directory in -Magnum source to `modules/` dir in your project (so it is able to find SDL2). -In case of Emscripten you need also `FindOpenGLES2.cmake`. Request -`Sdl2Application` component of `Magnum` package and link to -`Magnum::Sdl2Application` target. If no other application is requested, you can -also use generic `Magnum::Application` alias to simplify porting. Again, see -@ref building and @ref cmake for more information. +In order to use this library from CMake, you need to copy `FindSDL2.cmake` from +the `modules/` directory in Magnum source to the `modules/` dir in your project +(so it is able to find the SDL2 library). In case of Emscripten you need also +`FindOpenGLES2.cmake` / `FindOpenGLES3.cmake`. Request the `Sdl2Application` +component of the `Magnum` package and link to the `Magnum::Sdl2Application` +target: + +@code{.cmake} +find_package(Magnum REQUIRED Sdl2Application) + +# ... +target_link_libraries(your-app Magnum::Sdl2Application) +@endcode + +If no other application is requested, you can also use the generic +`Magnum::Application` alias to simplify porting. Again, see @ref building and +@ref cmake for more information. In C++ code you need to implement at least @ref drawEvent() to be able to draw on the screen. The subclass can be then used directly in `main()` --- see diff --git a/src/Magnum/Platform/WindowlessCglApplication.h b/src/Magnum/Platform/WindowlessCglApplication.h index 952bb00db..3c1977684 100644 --- a/src/Magnum/Platform/WindowlessCglApplication.h +++ b/src/Magnum/Platform/WindowlessCglApplication.h @@ -160,11 +160,24 @@ See @ref cmake for more information. @section Platform-WindowlessCglApplication-usage General usage -In CMake you need to request `WindowlessCglApplication` component of `Magnum` -package and link to `Magnum::WindowlessCglApplication` target. If no other -application is requested, you can also use generic `Magnum::Application` alias -to simplify porting. Again, see @ref building and @ref cmake for more -information. +In order to use this library from CMake, you need to request the +`WindowlessCglApplication` component of the `Magnum` package and link to the `Magnum::WindowlessCglApplication` target: + +@code{.cmake} +find_package(Magnum REQUIRED) +if(CORRADE_TARGET_APPLE) + find_package(Magnum REQUIRED WindowlessCglApplication) +endif() + +# ... +if(CORRADE_TARGET_APPLE) + target_link_libraries(your-app Magnum::WindowlessCglApplication) +endif() +@endcode + +If no other application is requested, you can also use the generic +`Magnum::WindowlessApplication` alias to simplify porting. Again, see +@ref building and @ref cmake for more information. Place your code into @ref exec(). The subclass can be then used directly in `main()` --- see convenience macro @ref MAGNUM_WINDOWLESSCGLAPPLICATION_MAIN(). diff --git a/src/Magnum/Platform/WindowlessEglApplication.h b/src/Magnum/Platform/WindowlessEglApplication.h index e2b45bcee..9b362520f 100644 --- a/src/Magnum/Platform/WindowlessEglApplication.h +++ b/src/Magnum/Platform/WindowlessEglApplication.h @@ -244,10 +244,22 @@ http://localhost/emscripten/MyApplication.html). @section Platform-WindowlessEglApplication-usage General usage -In CMake you need to request `WindowlessEglApplication` component and link to -`Magnum::WindowlessEglApplication` target. If no other windowless application -is requested, you can also use generic `Magnum::WindowlessApplication` alias to -simplify porting. Again, see @ref building and @ref cmake for more information. +In order to use this library from CMake, you need to copy `FindEGL.cmake` from +the modules directory in Magnum source to the `modules/` dir in your project +(so it is able to find the EGL library). Request the `WindowlessEglApplication` +component of the `Magnum` package and link to the +`Magnum::WindowlessEglApplication` target: + +@code{.cmake} +find_package(Magnum REQUIRED WindowlessEglApplication) + +# ... +target_link_libraries(your-app Magnum::WindowlessEglApplication) +@endcode + +If no other application is requested, you can also use the generic +`Magnum::WindowlessApplication` alias to simplify porting. Again, see +@ref building and @ref cmake for more information. Place your code into @ref exec(). The subclass can be then used in main function using @ref MAGNUM_WINDOWLESSEGLAPPLICATION_MAIN() macro. See diff --git a/src/Magnum/Platform/WindowlessGlxApplication.h b/src/Magnum/Platform/WindowlessGlxApplication.h index 685f9f18b..244acc5af 100644 --- a/src/Magnum/Platform/WindowlessGlxApplication.h +++ b/src/Magnum/Platform/WindowlessGlxApplication.h @@ -209,9 +209,22 @@ See @ref cmake for more information. @section Platform-WindowlessGlxApplication-usage General usage -In CMake you need to request `WindowlessGlxApplication` component of `Magnum` -package and link to `Magnum::WindowlessGlxApplication` target. If no other -windowless application is requested, you can also use generic +In order to use this library from CMake, you need to request the +`WindowlessGlxApplication` component of the `Magnum` package and link to the `Magnum::WindowlessGlxApplication` target: + +@code{.cmake} +find_package(Magnum REQUIRED) +if(CORRADE_TARGET_UNIX) + find_package(Magnum REQUIRED WindowlessGlxApplication) +endif() + +# ... +if(CORRADE_TARGET_UNIX) + target_link_libraries(your-app Magnum::WindowlessGlxApplication) +endif() +@endcode + +If no other application is requested, you can also use the generic `Magnum::WindowlessApplication` alias to simplify porting. Again, see @ref building and @ref cmake for more information. diff --git a/src/Magnum/Platform/WindowlessIosApplication.h b/src/Magnum/Platform/WindowlessIosApplication.h index be26f17fe..d99b53eda 100644 --- a/src/Magnum/Platform/WindowlessIosApplication.h +++ b/src/Magnum/Platform/WindowlessIosApplication.h @@ -155,10 +155,27 @@ See @ref cmake for more information. @section Platform-WindowlessIosApplication-usage General usage -In CMake you need to request `WindowlessIosApplication` component and link to -`Magnum::WindowlessIosApplication` target. If no other windowless application -is requested, you can also use generic `Magnum::WindowlessApplication` alias to -simplify porting. Again, see @ref building and @ref cmake for more information. +In order to use this library from CMake, you need to copy `FindEGL.cmake` from +the modules directory in Magnum source to the `modules/` dir in your project +(so it is able to find the EGL library). Request the `WindowlessIosApplication` +component of the `Magnum` package and link to the +`Magnum::WindowlessIosApplication` target: + +@code{.cmake} +find_package(Magnum REQUIRED) +if(CORRADE_TARGET_IOS) + find_package(Magnum REQUIRED WindowlessIosApplication) +endif() + +# ... +if(CORRADE_TARGET_IOS) + target_link_libraries(your-app Magnum::WindowlessIosApplication) +endif() +@endcode + +If no other application is requested, you can also use the generic +`Magnum::WindowlessApplication` alias to simplify porting. Again, see +@ref building and @ref cmake for more information. Place your code into @ref exec(). The subclass can be then used in main function using @ref MAGNUM_WINDOWLESSIOSAPPLICATION_MAIN() macro. See diff --git a/src/Magnum/Platform/WindowlessWglApplication.h b/src/Magnum/Platform/WindowlessWglApplication.h index ce5b4c3a3..f33d7ee02 100644 --- a/src/Magnum/Platform/WindowlessWglApplication.h +++ b/src/Magnum/Platform/WindowlessWglApplication.h @@ -208,9 +208,22 @@ See @ref cmake for more information. @section Platform-WindowlessWglApplication-usage General usage -In CMake you need to request `WindowlessWglApplication` component of `Magnum` -package and link to `Magnum::WindowlessWglApplication` target. If no other -windowless application is requested, you can also use generic +In order to use this library from CMake, you need to request the +`WindowlessWglApplication` component of the `Magnum` package and link to the `Magnum::WindowlessWglApplication` target: + +@code{.cmake} +find_package(Magnum REQUIRED) +if(CORRADE_TARGET_WINDOWS) + find_package(Magnum REQUIRED WindowlessWglApplication) +endif() + +# ... +if(CORRADE_TARGET_WINDOWS) + target_link_libraries(your-app Magnum::WindowlessWglApplication) +endif() +@endcode + +If no other application is requested, you can also use the generic `Magnum::WindowlessApplication` alias to simplify porting. Again, see @ref building and @ref cmake for more information. diff --git a/src/Magnum/Platform/WindowlessWindowsEglApplication.h b/src/Magnum/Platform/WindowlessWindowsEglApplication.h index cd8e8a475..47d8a210c 100644 --- a/src/Magnum/Platform/WindowlessWindowsEglApplication.h +++ b/src/Magnum/Platform/WindowlessWindowsEglApplication.h @@ -195,9 +195,25 @@ See @ref cmake for more information. @section Platform-WindowlessWindowsEglApplication-usage General usage -In CMake you need to request `WindowlessWindowsEglApplication` component of -`Magnum` package and link to `Magnum::WindowlessWindowsEglApplication` target. -If no other windowless application is requested, you can also use generic +In order to use this library from CMake, you need to copy `FindEGL.cmake` from +the modules directory in Magnum source to the `modules/` dir in your project +(so it is able to find the EGL library). Request the +`WindowlessWindowsEglApplication` component of the `Magnum` package and link to +the `Magnum::WindowlessGlxApplication` target: + +@code{.cmake} +find_package(Magnum REQUIRED) +if(CORRADE_TARGET_WINDOWS) + find_package(Magnum REQUIRED WindowlessWindowsEglApplication) +endif() + +# ... +if(CORRADE_TARGET_WINDOWS) + target_link_libraries(your-app Magnum::WindowlessWindowsEglApplication) +endif() +@endcode + +If no other application is requested, you can also use the generic `Magnum::WindowlessApplication` alias to simplify porting. Again, see @ref building and @ref cmake for more information. diff --git a/src/Magnum/Platform/XEglApplication.h b/src/Magnum/Platform/XEglApplication.h index e934bf851..951509b1e 100644 --- a/src/Magnum/Platform/XEglApplication.h +++ b/src/Magnum/Platform/XEglApplication.h @@ -51,12 +51,22 @@ more information. @section Platform-XEglApplication-usage General usage -For CMake you need to copy `FindEGL.cmake` from `modules/` directory in Magnum -source to `modules/` dir in your project (so it is able to find EGL), request -`XEglApplication` component of `Magnum` package and link to -`Magnum::XEglApplication` target. If no other application is requested, you -can also use generic `Magnum::Application` alias to simplify porting. See -@ref building and @ref cmake for more information. +In order to use this library from CMake, you need to copy `FindEGL.cmake` from +the modules directory in Magnum source to the `modules/` dir in your project +(so it is able to find the EGL library). Request the `XEglApplication` +component of the `Magnum` package and link to the `Magnum::XEglApplication` +target: + +@code{.cmake} +find_package(Magnum REQUIRED XEglApplication) + +# ... +target_link_libraries(your-app Magnum::XEglApplication) +@endcode + +If no other application is requested, you can also use the generic +`Magnum::Application` alias to simplify porting. Again, see @ref building and +@ref cmake for more information. In C++ code you need to implement at least @ref drawEvent() to be able to draw on the screen. The subclass can be then used directly in @cpp main() @ce diff --git a/src/Magnum/Trade/AbstractImageConverter.h b/src/Magnum/Trade/AbstractImageConverter.h index 13028f01b..4e15cf40f 100644 --- a/src/Magnum/Trade/AbstractImageConverter.h +++ b/src/Magnum/Trade/AbstractImageConverter.h @@ -49,25 +49,26 @@ Provides functionality for converting images between various internal formats or compressing them. See @ref plugins for more information and `*ImageConverter` classes in @ref Trade namespace for available image converter plugins. -## Subclassing +@section Trade-AbstractImageConverter-subclassing Subclassing -Plugin implements function @ref doFeatures() and one or more of +The plugin needs to implement the@ref doFeatures() function and one or more of @ref doExportToImage(), @ref doExportToCompressedImage(), @ref doExportToData() or @ref doExportToFile() functions based on what features are supported. You don't need to do most of the redundant sanity checks, these things are checked by the implementation: -- Function @ref doExportToImage() is called only if @ref Feature::ConvertImage +- The function @ref doExportToImage() is called only if + @ref Feature::ConvertImage is supported. -- Function @ref doExportToCompressedImage() is called only if +- The function @ref doExportToCompressedImage() is called only if @ref Feature::ConvertCompressedImage is supported. -- Function @ref doExportToData(const ImageView2D&) is called only if +- The function @ref doExportToData(const ImageView2D&) is called only if @ref Feature::ConvertData is supported. -- Function @ref doExportToData(const CompressedImageView2D&) is called only - if @ref Feature::ConvertCompressedData is supported. +- The function @ref doExportToData(const CompressedImageView2D&) is called + only if @ref Feature::ConvertCompressedData is supported. -Plugin interface string is `"cz.mosra.magnum.Trade.AbstractImageConverter/0.2.1"`. +Plugin interface string is @cpp "cz.mosra.magnum.Trade.AbstractImageConverter/0.2.1" @ce. @attention @ref Corrade::Containers::Array instances returned from the plugin should *not* use anything else than the default deleter, otherwise this can diff --git a/src/Magnum/Trade/AbstractImporter.h b/src/Magnum/Trade/AbstractImporter.h index ead9c06a2..108c8ddd4 100644 --- a/src/Magnum/Trade/AbstractImporter.h +++ b/src/Magnum/Trade/AbstractImporter.h @@ -51,32 +51,33 @@ 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. -## Subclassing +@section Trade-AbstractImporter-subclassing Subclassing -Plugin implements function @ref doFeatures(), @ref doIsOpened(), one of or both -@ref doOpenData() and @ref doOpenFile() functions, function @ref doClose() and -one or more tuples of data access functions, based on which features are -supported in given format. +The plugin needs to implement the @ref doFeatures(), @ref doIsOpened() +functions, one of or both @ref doOpenData() and @ref doOpenFile() functions, +function @ref doClose() and one or more tuples of data access functions, based +on which features are supported in given format. -For multi-data formats file opening shouldn't take long, all parsing should -be done in data parsing functions, because the user might want to import only -some data. This is obviously not the case for single-data formats like images, -as the file contains all data user wants to import. +For multi-data formats the file opening shouldn't take long and all parsing +should be done in the data parsing functions instead, because the user might +want to import only some data. This is obviously not the case for single-data +formats like images, as the file contains all the data the user wants to +import. You don't need to do most of the redundant sanity checks, these things are checked by the implementation: -- Functions @ref doOpenData() and @ref doOpenFile() are called after the +- The @ref doOpenData() and @ref doOpenFile() functions are called after the previous file was closed, function @ref doClose() is called only if there is any file opened. -- Function @ref doOpenData() is called only if @ref Feature::OpenData is +- The @ref doOpenData() function is called only if @ref Feature::OpenData is supported. -- All `do*()` implementations working on opened file are called only if there - is any file opened. +- All `do*()` implementations working on an opened file are called only if + there is any file opened. - All `do*()` implementations taking data ID as parameter are called only if the ID is from valid range. -Plugin interface string is `"cz.mosra.magnum.Trade.AbstractImporter/0.3"`. +Plugin interface string is @cpp "cz.mosra.magnum.Trade.AbstractImporter/0.3" @ce. @attention @ref Corrade::Containers::Array instances returned from the plugin should *not* use anything else than the default deleter, otherwise this can diff --git a/src/MagnumPlugins/MagnumFont/MagnumFont.h b/src/MagnumPlugins/MagnumFont/MagnumFont.h index 845241f86..a2ebb5e1e 100644 --- a/src/MagnumPlugins/MagnumFont/MagnumFont.h +++ b/src/MagnumPlugins/MagnumFont/MagnumFont.h @@ -55,71 +55,72 @@ 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 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` target. See @ref building, @ref cmake and @ref plugins for -more information. +This plugin depends on the @ref Text library and the +@ref Trade::TgaImporter "TgaImporter" plugin. It is built if `WITH_MAGNUMFONT` +is enabled when building Magnum. To use as a dynamic plugin, you need to load +the @cpp "MagnumFont" @ce plugin from `MAGNUM_PLUGINS_FONT_DIR`. To use as a +static plugin or as a dependency of another plugin with CMake, you need to +request the `MagnumFont` component of the `Magnum` package and link to the +`Magnum::MagnumFont` target. 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 -can be conveniently created from any other format using MagnumFontConverter. -The file syntax is as in following: +can be conveniently created from any other format using +@ref MagnumFontConverter. The file syntax is as in following: - # Font image filename - image=font.tga +@code{.ini} +# Font image filename +image=font.tga - # Size of unscaled font image - originalImageSize=1536 1536 +# Size of unscaled font image +originalImageSize=1536 1536 - # Glyph padding - padding=9 +# Glyph padding +padding=9 - # Font size - fontSize=128 +# Font size +fontSize=128 - # Line height - lineHeight=270 +# Line height +lineHeight=270 - # Character - [char] +# Character +[char] - # UTF-32 codepoint ('a') - unicode=0061 +# UTF-32 codepoint ('a') +unicode=0061 - # Glyph ID - glyph=1 +# Glyph ID +glyph=1 - # Advance to next character in pixels (i.e. on unscaled font image) - advance=45 0 +# Advance to next character in pixels (i.e. on unscaled font image) +advance=45 0 - # Another character - [char] - unicode=0062 - glyph=2 - advance=42 0 +# Another character +[char] +unicode=0062 +glyph=2 +advance=42 0 - # ... +# ... - # Glyph 0, a.k.a. "Not Found" glyph - [glyph] +# Glyph 0, a.k.a. "Not Found" glyph +[glyph] - # Glyph texture position relative to baseline, in pixels - position=5 -1 +# Glyph texture position relative to baseline, in pixels +position=5 -1 - # Glyph rectangle in font image, in pixels (left, bottom, right, top) - rectangle=0 0 42 25 +# Glyph rectangle in font image, in pixels (left, bottom, right, top) +rectangle=0 0 42 25 - # Glyph 1 - [glyph] - position=0 0 - rectangle=45 0 44 25 +# Glyph 1 +[glyph] +position=0 0 +rectangle=45 0 44 25 - # ... - -@see @ref Trade::TgaImporter +# ... +@endcode */ class MAGNUM_MAGNUMFONT_EXPORT MagnumFont: public AbstractFont { public: diff --git a/src/MagnumPlugins/MagnumFontConverter/MagnumFontConverter.h b/src/MagnumPlugins/MagnumFontConverter/MagnumFontConverter.h index 77e1ee430..59e615579 100644 --- a/src/MagnumPlugins/MagnumFontConverter/MagnumFontConverter.h +++ b/src/MagnumPlugins/MagnumFontConverter/MagnumFontConverter.h @@ -58,14 +58,15 @@ Expects filename prefix, creates two files, `prefix.conf` and `prefix.tga`. See @ref MagnumFont for more information about the font. 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 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` -target. See @ref building, @ref cmake and @ref plugins for more information. +to read back the generated data. It depends on the @ref Text library and the +@ref Trade::TgaImageConverter "TgaImageConverter" plugin. It is built if +`WITH_MAGNUMFONTCONVERTER` is enabled when building Magnum. To use as a +dynamic plugin, you need to load the @cpp "MagnumFontConverter" @ce plugin from +`MAGNUM_PLUGINS_FONTCONVERTER_DIR`. To use as a static plugin or as a +dependency of another plugin with CMake, you need to request the +`MagnumFontConverter` component of the `Magnum` package and link to the +`Magnum::MagnumFontConverter` target. See @ref building, @ref cmake and +@ref plugins for more information. */ class MAGNUM_MAGNUMFONTCONVERTER_EXPORT MagnumFontConverter: public Text::AbstractFontConverter { public: diff --git a/src/MagnumPlugins/ObjImporter/ObjImporter.h b/src/MagnumPlugins/ObjImporter/ObjImporter.h index 6972cb940..81ec77dce 100644 --- a/src/MagnumPlugins/ObjImporter/ObjImporter.h +++ b/src/MagnumPlugins/ObjImporter/ObjImporter.h @@ -60,15 +60,18 @@ Loads Wavefront OBJ (`*.obj`) files, with the following supported features: - vertex positions, normals and 2D texture coordinates - triangles, lines and points +This plugin depends on the @ref Trade library and is built if `WITH_OBJIMPORTER` +is enabled when building Magnum. To use as a dynamic plugin, you need to load +the @cpp "ObjImporter" @ce plugin from `MAGNUM_PLUGINS_IMPORTER_DIR`. To use as +a static plugin or as a dependency of another plugin with CMake, you need to +request the `ObjImporter` component of the `Magnum` package and link to the +`Magnum::ObjImporter` target. See @ref building, @ref cmake and @ref plugins +for more information. + +@section Trade-ObjImporter-limitations Behavior and limitations + Polygons (quads etc.), automatic normal generation and material properties are currently not supported. - -This plugin is built if `WITH_OBJIMPORTER` is enabled when building Magnum. To -use dynamic plugin, you need to load `ObjImporter` plugin from -`MAGNUM_PLUGINS_IMPORTER_DIR`. To use static plugin or use this as a dependency -of another plugin, you need to request `ObjImporter` component of `Magnum` -package in CMake and link to `Magnum::ObjImporter` target. See @ref building, -@ref cmake and @ref plugins for more information. */ class MAGNUM_OBJIMPORTER_EXPORT ObjImporter: public AbstractImporter { public: diff --git a/src/MagnumPlugins/TgaImageConverter/TgaImageConverter.h b/src/MagnumPlugins/TgaImageConverter/TgaImageConverter.h index cebd6e574..37b6ed8b7 100644 --- a/src/MagnumPlugins/TgaImageConverter/TgaImageConverter.h +++ b/src/MagnumPlugins/TgaImageConverter/TgaImageConverter.h @@ -57,15 +57,20 @@ namespace Magnum { namespace Trade { Creates Truevision TGA (`*.tga`) files from images with format @ref PixelFormat::RGB, @ref PixelFormat::RGBA or @ref PixelFormat::Red (or @ref PixelFormat::Luminance in OpenGL ES 2.0 and WebGL 1.0) and type -@ref PixelType::UnsignedByte. Does *not* support non-default -@ref PixelStorage::swapBytes() values. - -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` -target. See @ref building, @ref cmake and @ref plugins for more information. +@ref PixelType::UnsignedByte. + +This plugin depends on the @ref Trade library and is built if +`WITH_TGAIMAGECONVERTER` is enabled when building Magnum. To use as a dynamic +plugin, you need to load the @cpp "TgaImageConverter" @ce plugin from +`MAGNUM_PLUGINS_IMAGECONVERTER_DIR`. To use as a static plugin or as a +dependency of another plugin with CMake, you need to request the +`TgaImageConverter` component of the `Magnum` package and link to the +`Magnum::TgaImageConverter` target. See @ref building, @ref cmake and +@ref plugins for more information. + +@section Trade-TgaImageConverter-limitations Behavior and limitations + +Does *not* support non-default @ref PixelStorage::swapBytes() values. */ class MAGNUM_TGAIMAGECONVERTER_EXPORT TgaImageConverter: public AbstractImageConverter { public: diff --git a/src/MagnumPlugins/TgaImporter/TgaImporter.h b/src/MagnumPlugins/TgaImporter/TgaImporter.h index 6aac9f4f8..a1d3e384d 100644 --- a/src/MagnumPlugins/TgaImporter/TgaImporter.h +++ b/src/MagnumPlugins/TgaImporter/TgaImporter.h @@ -60,12 +60,13 @@ namespace Magnum { namespace Trade { Supports Truevision TGA (`*.tga`, `*.vda`, `*.icb`, `*.vst`) uncompressed BGR, BGRA or grayscale images with 8 bits per channel. -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` target. See @ref building, -@ref cmake and @ref plugins for more information. +This plugin depends on the @ref Trade library and is built if `WITH_TGAIMPORTER` +is enabled when building Magnum. To use as a dynamic plugin, you need to load +the @cpp "TgaImporter" @ce plugin from `MAGNUM_PLUGINS_IMPORTER_DIR`. To use as +a static plugin or use this as a dependency of another plugin with CMake, you +need to request the `TgaImporter` component of the `Magnum` package and link to +the `Magnum::TgaImporter` target. See @ref building, @ref cmake and +@ref plugins for more information. The images are imported with @ref PixelType::UnsignedByte and @ref PixelFormat::RGB, @ref PixelFormat::RGBA or @ref PixelFormat::Red, respectively. Grayscale images diff --git a/src/MagnumPlugins/WavAudioImporter/WavImporter.h b/src/MagnumPlugins/WavAudioImporter/WavImporter.h index bc37c9555..6a9223fa4 100644 --- a/src/MagnumPlugins/WavAudioImporter/WavImporter.h +++ b/src/MagnumPlugins/WavAudioImporter/WavImporter.h @@ -66,14 +66,17 @@ Supports mono and stereo files of the following formats: - A-Law, imported as @ref Buffer::Format::MonoALaw / @ref Buffer::Format::StereoALaw - μ-Law, imported as @ref Buffer::Format::MonoMuLaw / @ref Buffer::Format::StereoMuLaw -Multi-channel formats are not supported. - 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 -of `Magnum` package in CMake and link to `Magnum::WavAudioImporter` target. See -@ref building, @ref cmake and @ref plugins for more information. +Magnum. To use dynamic plugin, you need to load the @cpp "WavAudioImporter" @ce +plugin from `MAGNUM_PLUGINS_AUDIOIMPORTER_DIR`. To use as a static plugin or as +a dependency of another plugin with CMake, you need to request the +`WavAudioImporter` component of the `Magnum` package and link to the +`Magnum::WavAudioImporter` target. See @ref building, @ref cmake and +@ref plugins for more information. + +@section Audio-WavImporter-limitations Behavior and limitations + +Multi-channel formats are not supported. */ class MAGNUM_WAVAUDIOIMPORTER_EXPORT WavImporter: public AbstractImporter { public: