diff --git a/doc/building.dox b/doc/building.dox index fc6a3e7d7..591071ec9 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -26,7 +26,7 @@ namespace Magnum { /** @page building Downloading and building -@brief Guide how to download and build %Magnum on different platforms. +@brief Guide how to download and build Magnum on different platforms. @tableofcontents @@ -149,16 +149,16 @@ Libraries and static plugins built in `Debug` configuration (e.g. with 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 +and plugin distinction is handled semi-automatically when using Magnum in depending projects, see @ref cmake for more information. -%Magnum by default does not install `FindMagnum.cmake`, as you should bundle +Magnum by default does not install `FindMagnum.cmake`, as you should bundle the module with your code instead of depending on it being in system location. You can install it by enabling `WITH_FIND_MODULE`. 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 +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. @@ -184,7 +184,7 @@ 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. Enables also building of - %MeshTools, %Primitives, %SceneGraph, %Shaders and %Shapes libraries. + MeshTools, Primitives, SceneGraph, Shaders and Shapes libraries. - `WITH_MESHTOOLS` - @ref MeshTools library. Enabled automatically if `WITH_DEBUGTOOLS` is enabled. - `WITH_PRIMITIVES` - @ref Primitives library. Enabled automatically if @@ -193,9 +193,9 @@ parameters you can specify which parts will be built and which not: `WITH_DEBUGTOOLS` or `WITH_SHAPES` is enabled. - `WITH_SHADERS` - @ref Shaders library. Enabled automatically if `WITH_DEBUGTOOLS` is enabled. -- `WITH_SHAPES` - @ref Shapes library. Enables also building of %SceneGraph +- `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 +- `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. @@ -231,12 +231,12 @@ on Linux, Mac OS X and Windows, also disabled by default: information about the engine and OpenGL capabilities. - `WITH_DISTANCEFIELDCONVERTER` - @ref magnum-distancefieldconverter "magnum-distancefieldconverter" executable for converting black&white images to distance field textures. - Enables also building of %TextureTools library. + Enables also building of TextureTools library. - `WITH_FONTCONVERTER` - @ref magnum-fontconverter "magnum-fontconverter" executable for converting fonts to raster ones. Enables also building of - %Text library. + Text library. -%Magnum also contains a set of dependency-less plugins for importing essential +Magnum also contains a set of dependency-less plugins for importing essential file formats. Additional plugins are provided in separate plugin repository, see @ref building-plugins for more information. None of the plugins is built by default. @@ -287,9 +287,9 @@ be build by running 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 +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-integration` +with Corrade's one. If related projects (`magnum-plugins`, `magnum-integration` and `magnum-examples`, see below) are places along these, their documentation will be also included in generated output. @@ -338,7 +338,7 @@ features, for example), modify the last entry in `debian/rules`. @section building-crosscompiling Crosscompiling For crosscompiling you need to have *both* target and native version of -%Corrade installed, because %Corrade needs to run `corrade-rc` utility on the +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. diff --git a/doc/cmake.dox b/doc/cmake.dox index 9a7199bc4..d545c04d3 100644 --- a/doc/cmake.dox +++ b/doc/cmake.dox @@ -25,14 +25,14 @@ namespace Magnum { /** @page cmake Usage with CMake -@brief Guide how to find and use %Magnum with CMake build system +@brief Guide how to find and use Magnum with CMake build system -%Magnum uses CMake build system for both building and integration into your +Magnum uses CMake build system for both building and integration into your projects. The logic is in module `FindMagnum.cmake` distributed with the engine in `modules/` directory, you are encouraged to copy it along with `FindCorrade.cmake` into your project and add path to the files to `CMAKE_MODULE_PATH`. Otherwise, if CMake won't be able to find this file in -predefined locations, it will error out even if %Magnum might be installed on +predefined locations, it will error out even if Magnum might be installed on the system. If you plan to use Magnum on OpenGL ES, you may also need `FindOpenGLES2.cmake` or `FindOpenGLES3.cmake` and in some cases also `FindEGL.cmake`. @@ -50,17 +50,17 @@ Basic usage is: find_package(Magnum REQUIRED) -This command tries to find base %Magnum library and then defines these +This command tries to find base Magnum library and then defines these variables: - `MAGNUM_FOUND` -- Whether the library was found -- `MAGNUM_LIBRARIES` -- %Magnum library and dependent libraries +- `MAGNUM_LIBRARIES` -- Magnum library and dependent libraries - `MAGNUM_INCLUDE_DIRS` -- Root include dir and include dirs of dependencies - `MAGNUM_PLUGINS_DEBUG_DIR` -- Base directory with dynamic plugins for debug - builds, defaults to `magnum-d/` subdirectory of dir where %Magnum library + builds, defaults to `magnum-d/` subdirectory of dir where Magnum library was found - `MAGNUM_PLUGINS_RELEASE_DIR` -- Base directory with dynamic plugins for - release builds, defaults to `magnum/` subdirectory of dir where %Magnum + release builds, defaults to `magnum/` subdirectory of dir where Magnum library was found - `MAGNUM_PLUGINS_DIR` -- Base directory with dynamic plugins, defaults to `MAGNUM_PLUGINS_RELEASE_DIR` in release builds and multi-configuration @@ -80,32 +80,32 @@ variables: dynamic audio importer plugins However, this command will try to find only the base library, not the optional -components. The base library depends on %Corrade and OpenGL libraries (or +components. The base library depends on Corrade and OpenGL libraries (or OpenGL ES libraries). Additional dependencies are specified by the components. The optional components are: -- `%Audio` -- @ref Audio library -- `%DebugTools` -- @ref DebugTools library (depends on `%MeshTools`, - `%Primitives`, `%SceneGraph`, `%Shaders` and `%Shapes` components) -- `%MeshTools` -- @ref MeshTools library -- `%Primitives` -- @ref Primitives library -- `%SceneGraph` -- @ref SceneGraph library -- `%Shaders` -- @ref Shaders library -- `%Shapes` -- @ref Shapes library (depends on `%SceneGraph` component) -- `%Text` -- @ref Text library (depends on `%TextureTools` component) -- `%TextureTools` -- @ref TextureTools library +- `Audio` -- @ref Audio library +- `DebugTools` -- @ref DebugTools library (depends on `MeshTools`, + `Primitives`, `SceneGraph`, `Shaders` and `Shapes` components) +- `MeshTools` -- @ref MeshTools library +- `Primitives` -- @ref Primitives library +- `SceneGraph` -- @ref SceneGraph library +- `Shaders` -- @ref Shaders library +- `Shapes` -- @ref Shapes library (depends on `SceneGraph` component) +- `Text` -- @ref Text library (depends on `TextureTools` component) +- `TextureTools` -- @ref TextureTools library Platform namespace is split into more components: -- `%GlutApplication` -- @ref Platform::GlutApplication "GlutApplication" -- `%GlxApplication` -- @ref Platform::GlxApplication "GlxApplication" -- `%NaClApplication` -- @ref Platform::NaClApplication "NaClApplication" -- `%Sdl2Application` -- @ref Platform::Sdl2Application "Sdl2Application" -- `%XEglApplication` -- @ref Platform::XEglApplication "XEglApplication" -- `%WindowlessCglApplication` -- @ref Platform::WindowlessCglApplication "WindowlessCglApplication" -- `%WindowlessGlxApplication` -- @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication" -- `%WindowlessNaClApplication` -- @ref Platform::WindowlessNaClApplication "WindowlessNaClApplication" -- `%WindowlessWglApplication` -- @ref Platform::WindowlessWglApplication "WindowlessWglApplication" +- `GlutApplication` -- @ref Platform::GlutApplication "GlutApplication" +- `GlxApplication` -- @ref Platform::GlxApplication "GlxApplication" +- `NaClApplication` -- @ref Platform::NaClApplication "NaClApplication" +- `Sdl2Application` -- @ref Platform::Sdl2Application "Sdl2Application" +- `XEglApplication` -- @ref Platform::XEglApplication "XEglApplication" +- `WindowlessCglApplication` -- @ref Platform::WindowlessCglApplication "WindowlessCglApplication" +- `WindowlessGlxApplication` -- @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication" +- `WindowlessNaClApplication` -- @ref Platform::WindowlessNaClApplication "WindowlessNaClApplication" +- `WindowlessWglApplication` -- @ref Platform::WindowlessWglApplication "WindowlessWglApplication" For manual context creation (without application wrappers) there are also platform-specific context libraries (see @ref platform-custom for more @@ -127,16 +127,16 @@ executable and then explicitly imported. Also if you are going to use them as dependencies, you need to find the dependency and then link to it. - `MagnumFont` -- @ref Text::MagnumFont "MagnumFont" plugin (depends on - `%Text` component and `TgaImporter` plugin) + `Text` component and `TgaImporter` plugin) - `MagnumFontConverter` -- @ref Text::MagnumFontConverter "MagnumFontConverter" - plugin (depends on `%Text` component and `%TgaImageConverter` plugin) + plugin (depends on `Text` component and `TgaImageConverter` plugin) - `ObjImporter` -- @ref Trade::ObjImporter "ObjImporter" plugin (depends on - `%MeshTools` component) + `MeshTools` component) - `TgaImageConverter` -- @ref Trade::TgaImageConverter "TgaImageConverter" plugin - `TgaImporter` -- @ref Trade::TgaImporter "TgaImporter" plugin - `WavAudioImporter` -- @ref Audio::WavImporter "WavAudioImporter" plugin - (depends on `%Audio` component) + (depends on `Audio` component) Note that [each namespace](namespaces.html), all @ref Platform libraries and each plugin class contain more detailed information about dependencies, @@ -172,7 +172,7 @@ You can make use of @ref corrade-cmake "CORRADE_IS_DEBUG_BUILD" preprocessor variable along with `MAGNUM_PLUGINS_*_DEBUG_DIR` / `MAGNUM_PLUGINS_*_RELEASE_DIR` variables to decide in preprocessing step. -Features of found %Magnum library are exposed in these CMake variables, they +Features of found Magnum library are exposed in these CMake variables, they are also available as preprocessor variables if including @ref Magnum/Magnum.h "Magnum/Magnum.h": @@ -192,7 +192,7 @@ contains path directly to Magnum directory (i.e. for includes without `Magnum/` prefix) and `MAGNUM_PLUGINS_INCLUDE_DIR` contains include dir for plugins (i.e. for includes without `MagnumPlugins/` prefix). -%Corrade library provides also its own set of CMake macros and variables, see +Corrade library provides also its own set of CMake macros and variables, see @ref corrade-cmake "its documentation" for more information. @ref cmake-plugins "Plugins repository" and @ref cmake-integration "Integration library" have also their own CMake modules. diff --git a/doc/coding-style.dox b/doc/coding-style.dox index 23dfb64a7..db8bf8c25 100644 --- a/doc/coding-style.dox +++ b/doc/coding-style.dox @@ -54,11 +54,11 @@ have `*.hpp` extension (hinting that they are something between `*.h` and @subsubsection coding-style-cpp-types Builtin types -Use %Magnum's own type aliases for public API (e.g. @ref UnsignedInt, see +Use Magnum's own type aliases for public API (e.g. @ref UnsignedInt, see @ref types for more information), but use specific types when interacting with third party libraries and OpenGL (e.g. `GLuint`) and rely only on implicit conversions when converting between them. This helps avoiding sign, truncation -and other issues, e.g. `%Math::%Vector2` will implicitly convert to +and other issues, e.g. `Math::Vector2` will implicitly convert to @ref Vector2i if and only if @ref Int is the same type as `GLsizei`. @subsubsection coding-style-cpp-naming Naming @@ -100,7 +100,7 @@ void setPolygonMode(PolygonMode mode); Additionally to @c \@todoc, @c \@debugoperator, @c \@debugoperatorenum, @c \@debugoperatorclassenum, @c \@configurationvalue and -@c \@configurationvalueref (same as in %Corrade), these are defined: +@c \@configurationvalueref (same as in Corrade), these are defined: @subsubsection coding-style-documentation-commands-collisionoperator Shape collision operators @@ -196,7 +196,7 @@ All classes and functions using those commands are cross-referenced in page In detailed documentation the text should be always first, the blocks are then ordered by their importance. Various @c \@note, @c \@attention and @c \@warning blocks to highlight some information are always first, then @c \@see block with -links to related stuff, where related %Magnum functions are first and links to +links to related stuff, where related Magnum functions are first and links to related GL API last, then various support information such as @c \@requires_glXX, @c \@requires_es_extension etc. (first desktop GL, then ES, then WebGL), after that @c \@deprecated_gl and @c \@deprecated information and diff --git a/doc/compilation-speedup.dox b/doc/compilation-speedup.dox index 533235ddc..a3ed6a930 100644 --- a/doc/compilation-speedup.dox +++ b/doc/compilation-speedup.dox @@ -30,7 +30,7 @@ namespace Magnum { @section compilation-forward-declarations Forward declarations instead of includes Essential thing when speeding up compilation is reducing number of `#``include` -directives in both headers and source files. %Magnum is strictly applying this +directives in both headers and source files. Magnum is strictly applying this policy in all header files, so all types which are not directly used in the header have only forward declarations. @@ -55,19 +55,19 @@ available, each namespace has its own: @section compilation-speedup-templates Templates -Many things in %Magnum are templated to allow handling of various types and +Many things in Magnum are templated to allow handling of various types and sizes of data, for example whole scene graph can operate either with @ref Float or @ref Double data type. However, having templated classes and function usually means that the compiler compiles the whole templated code again in each compilation unit (i.e. source file). In linking stage of the application or library the duplicates are just thrown out, which is a waste of compilation -time. A few techniques are employed in %Magnum to avoid this. +time. A few techniques are employed in Magnum to avoid this. @subsection compilation-speedup-hpp Template headers and implementation files When templated code is too large, it is not stored in header file, but in so-called *template implementation file*. Generally, all header files in -%Magnum have `*.h` extension and all source files have `*.cpp` extension. +Magnum have `*.h` extension and all source files have `*.cpp` extension. Template implementation files have `*.hpp` extension, hinting that they are something between `*.h` and `*.cpp` files. @@ -111,7 +111,7 @@ precious compilation time. Keyword `extern template` is a new thing in C++11, attempting to solve compilation time problems related to templated code. However, on some compilers -it causes conflicting symbol errors when used on whole classes, thus in %Magnum +it causes conflicting symbol errors when used on whole classes, thus in Magnum it's used only for specific functions. This is completely transparent to end user, so no special care is needed. diff --git a/doc/debug-tools.dox b/doc/debug-tools.dox index 042b87978..34ebfba7c 100644 --- a/doc/debug-tools.dox +++ b/doc/debug-tools.dox @@ -39,7 +39,7 @@ information about building and usage with CMake. @section debug-tools-renderers Debug renderers -%Debug renderers provide a way to visualize objects and object features in +Debug renderers provide a way to visualize objects and object features in @ref scenegraph "scene graph" without the need to mess around with meshes and shaders. They are implemented as object features, so you can attach any number of them to any object. diff --git a/doc/getting-started.dox b/doc/getting-started.dox index 396fc4e92..084cc03c3 100644 --- a/doc/getting-started.dox +++ b/doc/getting-started.dox @@ -25,7 +25,7 @@ namespace Magnum { /** @page getting-started Getting started -@brief Get started with %Magnum in matter of minutes. +@brief Get started with Magnum in matter of minutes. @tableofcontents @@ -42,7 +42,7 @@ parameter. @section getting-started-bootstrap Download bootstrap project Setting up a new project can be pretty gruesome and nobody likes repeating the -same process every time. %Magnum provides "bootstrap" project structures for +same process every time. Magnum provides "bootstrap" project structures for many use cases, helping you get up and running in no time. The [bootstrap repository](https://github.com/mosra/magnum-bootstrap) is @@ -67,7 +67,7 @@ so the compatibility mode gets properly detected and used. @section getting-started-review Review project structure -The base project consists of just six files in two subfolders. %Magnum uses +The base project consists of just six files in two subfolders. Magnum uses CMake build system, see @ref cmake for more information. modules/FindCorrade.cmake @@ -94,7 +94,7 @@ add_subdirectory(src) Directory `modules/` contains CMake modules for finding the needed dependencies. Unlike modules for finding e.g. OpenGL, which are part of standard CMake installation, these aren't part of it and thus must be -distributed with the project. These files are just verbatim copied from %Magnum +distributed with the project. These files are just verbatim copied from Magnum repository. Directory `src/` contains the actual project. To keep things simple, the @@ -130,7 +130,7 @@ MAGNUM_APPLICATION_MAIN(MyApplication) The application essentially does nothing, just clears screen framebuffer to default (dark gray) color and then does buffer swap to actually display it on -the screen. `CMakeLists.txt` finds %Magnum, sets up compiler flags, creates the +the screen. `CMakeLists.txt` finds Magnum, sets up compiler flags, creates the executable and links it to all needed libraries: @code find_package(Magnum REQUIRED Sdl2Application) @@ -176,7 +176,7 @@ everything is ready to be built. If CMake isn't able to find the dependencies on Windows, you might want to look at @ref building-windows. If CMake complains about `Sdl2Application` missing, -you forgot to enable `WITH_SDL2APPLICATION` when building %Magnum, +you forgot to enable `WITH_SDL2APPLICATION` when building Magnum, @ref getting-started-download "go back and fix it". @image html getting-started.png diff --git a/doc/mainpage.dox b/doc/mainpage.dox index 47140d8ed..d9bf279fa 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -26,7 +26,7 @@ namespace Magnum { /** @mainpage -%Magnum is 2D/3D graphics engine written in C++11 and modern OpenGL. Its goal +Magnum is 2D/3D graphics engine written in C++11 and modern OpenGL. Its goal is to simplify low-level graphics development and interaction with OpenGL using recent C++11 features and to abstract away platform-specific issues. @@ -37,19 +37,19 @@ recent C++11 features and to abstract away platform-specific issues. usually just an afterthought, if it is present at all. If you want to do your next project in 2D only, you have to either relearn another engine from scratch or emulate it in 3D, leaving many things overly complicated. - %Magnum treats 2D equivalently to 3D so you can reuse what you already + Magnum treats 2D equivalently to 3D so you can reuse what you already learned for 3D and even combine 2D and 3D in one project. - **Forward compatibility** If newer technology makes things faster, simpler or more intuitive, it is - the way to go. %Magnum by default relies on decent C++11 support and modern + the way to go. Magnum by default relies on decent C++11 support and modern OpenGL features and if some feature isn't available, it tries to emulate it using older functionality. However, you are not restricted to use the older functionality directly, if you really want to. - **Intuitive, but not restrictive API** Scripting languages are often preferred to C/C++ because they are designed - to have less complicated APIs and less boilerplate code. %Magnum is + to have less complicated APIs and less boilerplate code. Magnum is designed with intuitivity in mind, but also with speed and static checks that strongly-typed native code offers. It wraps OpenGL into less verbose and more type-safe API, which is easier to use. Usually the most common way @@ -121,7 +121,7 @@ Feel free to get more information or contact the author at: @section mainpage-license License -%Magnum is licensed under MIT/Expat license: +Magnum is licensed under MIT/Expat license: > > Copyright © 2010, 2011, 2012, 2013, 2014 diff --git a/doc/matrix-vector.dox b/doc/matrix-vector.dox index d57326320..4c80c4bae 100644 --- a/doc/matrix-vector.dox +++ b/doc/matrix-vector.dox @@ -31,7 +31,7 @@ namespace Magnum { - Next page: @ref transformations Matrices and vectors are the most important part of graphics programming and -one of goals of %Magnum is to make their usage as intuitive as possible. They +one of goals of Magnum is to make their usage as intuitive as possible. They are contained in @ref Math namespace and common variants also have aliases in root @ref Magnum namespace. See documentation of these namespaces for more information about usage with CMake. @@ -40,10 +40,10 @@ information about usage with CMake. @section matrix-vector-hierarchy Matrix and vector classes -%Magnum has three main matrix and vector classes: @ref Math::RectangularMatrix, +Magnum has three main matrix and vector classes: @ref Math::RectangularMatrix, (square) @ref Math::Matrix and @ref Math::Vector. To achieve greatest code -reuse, %Matrix is internally square %RectangularMatrix and %RectangularMatrix -is internally array of one or more %Vector instances. Both vectors and matrices +reuse, Matrix is internally square RectangularMatrix and RectangularMatrix +is internally array of one or more Vector instances. Both vectors and matrices can have arbitrary size (known at compile time) and can store any arithmetic type. @@ -53,14 +53,14 @@ vector and matrix sizes there are specialized classes @ref Math::Matrix3 and @ref Math::Vector2, @ref Math::Vector3 and @ref Math::Vector4, implementing direct access to named components. Functions of each class try to return the most specialized type known to make subsequent operations more convenient -- -columns of %RectangularMatrix are returned as %Vector, but when accessing -columns of e.g. %Matrix3, they are returned as %Vector3. +columns of RectangularMatrix are returned as Vector, but when accessing +columns of e.g. Matrix3, they are returned as Vector3. There are also even more specialized subclasses, e.g. @ref Color3 and @ref Color4 for color handling and conversion. Commonly used types have convenience aliases in @ref Magnum namespace, so you -can write e.g. `%Vector3i` instead of `%Math::Vector3`. See @ref types and +can write e.g. `Vector3i` instead of `Math::Vector3`. See @ref types and namespace documentation for more information. @section matrix-vector-construction Constructing matrices and vectors @@ -198,7 +198,7 @@ available component-wise operations. @section matrix-vector-operations Operations with matrices and vectors Vectors can be added, subtracted, negated and multiplied or divided with -scalars, as is common in mathematics, %Magnum also adds the ability to divide +scalars, as is common in mathematics, Magnum also adds the ability to divide scalar with vector: @code Vector3 a(1.0f, 2.0f, 3.0f); @@ -214,7 +214,7 @@ Vector3 b = a*Vector3(-0.5f, 2.0f, -7.0f); // b == {-0.5f, 4.0f, -21.0f} When working with integral vectors (i.e. 24bit RGB values), it is often desirable to multiply them with floating-point values but with integral result. -In %Magnum all mulitplication/division operations involving integral vectors +In Magnum all mulitplication/division operations involving integral vectors will have integral result, you need to convert both arguments to the same floating-point type to have floating-point result. @code @@ -315,7 +315,7 @@ auto b = Math::denormalize(0.89f); // 226 @section matrix-vector-column-major Matrices are column-major and vectors are columns OpenGL matrices are column-major, thus it is reasonable to have matrices in -%Magnum also column major (and vectors as columns). This has naturally some +Magnum also column major (and vectors as columns). This has naturally some implications and it may differ from what is common in mathematics: - Order of template arguments in specification of @ref Math::RectangularMatrix diff --git a/doc/method-chaining.dox b/doc/method-chaining.dox index 484dc0347..9a8a9c9cb 100644 --- a/doc/method-chaining.dox +++ b/doc/method-chaining.dox @@ -33,12 +33,12 @@ feature which allows you to chain method calls one after another without repeatedly specifying variable the method is called on. Its primary goal is to reduce unnecessary repeated names, improving code readability. -%Magnum uses this feature mainly for configuring OpenGL objects (such as +Magnum uses this feature mainly for configuring OpenGL objects (such as various mesh and framebuffer options, shader uniforms etc.). Because OpenGL was designed with "bind-to-modify" approach, most configuration calls internally need to bind the object first and only after that change the parameters (unless @extension{EXT,direct_state_access} extension is available to avoid this). To -reduce unneeded bind calls, %Magnum binds the object only if it is not already +reduce unneeded bind calls, Magnum binds the object only if it is not already bound somewhere. Method chaining encourages you to configure whole object in one run, effectively reducing the number of needed bindings. Consider the following example: diff --git a/doc/namespaces.dox b/doc/namespaces.dox index 0298aa27b..365efd7f4 100644 --- a/doc/namespaces.dox +++ b/doc/namespaces.dox @@ -31,8 +31,8 @@ Contains classes for interacting with OpenGL. -This library is built as part of %Magnum by default. To use it, you need to -find `%Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link +This library is built as part of Magnum by default. To use it, you need to +find `Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and @ref cmake for more information. */ @@ -46,9 +46,9 @@ information. 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 +building Magnum, with each library having specific toolkit dependencies and platform requirements. To use particular application library, you need to -request given `*Application` component of `%Magnum` package in CMake, add +request given `*Application` component of `Magnum` package in CMake, add `${MAGNUM_*APPLICATION_INCLUDE_DIRS}` to include path and link to `${MAGNUM_*APPLICATION_LIBRARIES}`. See particular `*Application` class documentation, @ref building, @ref cmake and @ref platform for more @@ -59,12 +59,12 @@ information. * @brief Namespace Magnum::Math */ /** @namespace Magnum::Math -@brief %Math library +@brief Math library 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, add `${MAGNUM_INCLUDE_DIRS}` to include path and link +This library is built as part of Magnum by default. To use it, you need to +find `Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building, @ref cmake, @ref matrix-vector and @ref transformations for more information. */ @@ -73,12 +73,12 @@ to `${MAGNUM_LIBRARIES}`. See @ref building, @ref cmake, @ref matrix-vector and * @brief Namespace Magnum::Math::Algorithms */ /** @namespace Magnum::Math::Algorithms -@brief %Algorithms +@brief Algorithms Various matrix and vector algorithms. -This library is built as part of %Magnum by default. To use it, you need to -find `%Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link +This library is built as part of Magnum by default. To use it, you need to +find `Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and @ref cmake for more information. */ @@ -87,12 +87,12 @@ information. * @brief Namespace Magnum::Math::Geometry */ /** @namespace Magnum::Math::Geometry -@brief %Geometry library +@brief Geometry library Functions for computing intersections, distances, areas and volumes. -This library is built as part of %Magnum by default. To use it, you need to -find `%Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link +This library is built as part of Magnum by default. To use it, you need to +find `Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and @ref cmake for more information. */ @@ -101,13 +101,13 @@ information. * @brief Namespace Magnum::Audio */ /** @namespace Magnum::Audio -@brief %Audio playback +@brief Audio playback 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, add `${MAGNUM_AUDIO_INCLUDE_DIRS}` +enabled when building Magnum. To use this library, you need to request +`Audio` component of `Magnum` package in CMake, add `${MAGNUM_AUDIO_INCLUDE_DIRS}` to include path and link to `${MAGNUM_AUDIO_LIBRARIES}`. See @ref building and @ref cmake for more information. Additional plugins are enabled separately, see particular `*Importer` class documentation, @ref building-plugins, @@ -118,12 +118,12 @@ particular `*Importer` class documentation, @ref building-plugins, * @brief Namespace Magnum::DebugTools */ /** @namespace Magnum::DebugTools -@brief %Debug tools +@brief Debug tools 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` +This library is built if `WITH_DEBUGTOOLS` is enabled when building Magnum. To +use this library, you need to request `DebugTools` component of `Magnum` package in CMake and link to `${MAGNUM_DEBUGTOOLS_LIBRARIES}`. See @ref building, @ref cmake and @ref debug-tools for more information. */ @@ -132,12 +132,12 @@ package in CMake and link to `${MAGNUM_DEBUGTOOLS_LIBRARIES}`. See * @brief Namespace Magnum::MeshTools */ /** @namespace Magnum::MeshTools -@brief %Mesh tools +@brief Mesh tools 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` +This library is built if `WITH_MESHTOOLS` is enabled when building Magnum. To +use this library, you need to request `MeshTools` component of `Magnum` package in CMake and link to `${MAGNUM_MESHTOOLS_LIBRARIES}`. See @ref building and @ref cmake for more information. */ @@ -150,8 +150,8 @@ and @ref cmake for more information. 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` +This library is built if `WITH_PRIMITIVES` is enabled when building Magnum. To +use this library, you need to request `Primitives` component of `Magnum` package in CMake and link to `${MAGNUM_PRIMITIVES_LIBRARIES}`. See @ref building and @ref cmake for more information. */ @@ -161,12 +161,12 @@ package in CMake and link to `${MAGNUM_PRIMITIVES_LIBRARIES}`. See */ /** @namespace Magnum::SceneGraph -@brief %Scene graph library +@brief Scene graph library 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` +This library is built if `WITH_SCENEGRAPH` is enabled when building Magnum. To +use this library, you need to request `SceneGraph` component of `Magnum` package in CMake and link to `${MAGNUM_SCENEGRAPH_LIBRARIES}`. See @ref building, @ref cmake and @ref scenegraph for more information. */ @@ -179,8 +179,8 @@ package in CMake and link to `${MAGNUM_SCENEGRAPH_LIBRARIES}`. See 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 +This library is built if `WITH_SHADERS` is enabled when building Magnum. To +use this library, you need to request `Shaders` component of `Magnum` package in CMake and link to `${MAGNUM_MESHTOOLS_SHADERS}`. See @ref building and @ref cmake for more information. */ @@ -189,12 +189,12 @@ in CMake and link to `${MAGNUM_MESHTOOLS_SHADERS}`. See @ref building and * @brief Namespace Magnum::Shapes */ /** @namespace Magnum::Shapes -@brief %Shape library +@brief Shape library 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 +This library is built if `WITH_SHAPES` is enabled when building Magnum. To use +this library, you need to request `Shapes` component of `Magnum` package in CMake and link to `${MAGNUM_SHAPES_LIBRARIES}`. See @ref building, @ref cmake and @ref shapes for more information. */ @@ -203,12 +203,12 @@ and @ref shapes for more information. * @brief Namespace Magnum::Text */ /** @namespace Magnum::Text -@brief %Text rendering +@brief Text rendering 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 +This library is built if `WITH_TEXT` is enabled when building Magnum. To use +this library, you need to request `Text` component of `Magnum` package in CMake and link to `${MAGNUM_TEXT_LIBRARIES}`. See @ref building and @ref cmake for more information. Additional plugins are enabled separately, see particular `*Font` and `*FontConverter` class documentation, @ref building-plugins, @@ -219,12 +219,12 @@ for more information. Additional plugins are enabled separately, see particular * @brief Namespace Magnum::TextureTools */ /** @namespace Magnum::TextureTools -@brief %Texture tools +@brief Texture tools 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` +This library is built if `WITH_TEXTURETOOLS` is enabled when building Magnum. +To use this library, you need to request `TextureTools` component of `Magnum` package in CMake and link to `${MAGNUM_TEXTURETOOLS_LIBRARIES}`. See @ref building and @ref cmake for more information. */ @@ -238,8 +238,8 @@ package in CMake and link to `${MAGNUM_TEXTURETOOLS_LIBRARIES}`. See 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, add `${MAGNUM_INCLUDE_DIRS}` to include path and link +This library is built as part of Magnum by default. To use it, you need to +find `Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and @ref cmake for more information. Additional plugins are enabled separately, see particular `*Importer` and `*ImageConverter` class documentation, @ref building-plugins, @@ -247,5 +247,5 @@ information. Additional plugins are enabled separately, see particular */ /** @dir magnum/src/MagnumPlugins - * @brief %Magnum plugins (part of @ref building "Magnum library") + * @brief Magnum plugins (part of @ref building "Magnum library") */ diff --git a/doc/opengl-mapping.dox b/doc/opengl-mapping.dox index b54e93c45..89e7b4a57 100644 --- a/doc/opengl-mapping.dox +++ b/doc/opengl-mapping.dox @@ -26,7 +26,7 @@ namespace Magnum { /** @page opengl-mapping OpenGL command mapping -@brief List of OpenGL commands corresponding to particular %Magnum API. +@brief List of OpenGL commands corresponding to particular Magnum API. @tableofcontents diff --git a/doc/opengl-support.dox b/doc/opengl-support.dox index cc51f839b..4623c5f70 100644 --- a/doc/opengl-support.dox +++ b/doc/opengl-support.dox @@ -50,7 +50,7 @@ following: @todo @extension{EXT,texture_array} overlaps with @extension{ARB,framebuffer_object} @todo Add @extension{ARB,depth_buffer_float} and implement the missing @fn_gl{DepthRange} function, but keep (and implement) @extension{NV,depth_buffer_float} for non-linear depth buffer -%Extension | Status +Extension | Status ------------------------------------------- | ------ GLSL 1.30 | done @extension{ARB,map_buffer_range} | done @@ -76,7 +76,7 @@ GLSL 1.30 | done @subsection opengl-support-31 OpenGL 3.1 -%Extension | Status +Extension | Status ------------------------------------------- | ------ GLSL 1.40 | done @extension{ARB,texture_rectangle} | done @@ -89,7 +89,7 @@ GLSL 1.40 | done @subsection opengl-support-32 OpenGL 3.2 -%Extension | Status +Extension | Status ------------------------------------------- | ------ GLSL 1.50 | done @extension{ARB,geometry_shader4} | missing layered attachments @@ -104,7 +104,7 @@ GLSL 1.50 | done @subsection opengl-support-33 OpenGL 3.3 -%Extension | Status +Extension | Status ------------------------------------------- | ------ GLSL 3.30 | done @extension{ARB,instanced_arrays} | done @@ -120,7 +120,7 @@ GLSL 3.30 | done @subsection opengl-support-40 OpenGL 4.0 -%Extension | Status +Extension | Status ------------------------------------------- | ------ GLSL 4.00 | done @extension{ARB,draw_buffers_blend} | | @@ -139,7 +139,7 @@ GLSL 4.00 | done @subsection opengl-support-41 OpenGL 4.1 -%Extension | Status +Extension | Status ------------------------------------------- | ------ GLSL 4.10 | done @extension{ARB,ES2_compatibility} | only float depth clear @@ -151,7 +151,7 @@ GLSL 4.10 | done @subsection opengl-support-42 OpenGL 4.2 -%Extension | Status +Extension | Status ------------------------------------------- | ------ GLSL 4.20 | done @extension{ARB,texture_compression_bptc} | done @@ -169,7 +169,7 @@ GLSL 4.20 | done @subsection opengl-support-43 OpenGL 4.3 -%Extension | Status +Extension | Status ------------------------------------------- | ------ GLSL 4.30 | done @extension{ARB,arrays_of_arrays} | done (shading language only) @@ -200,7 +200,7 @@ GLSL 4.30 | done @todo Also fallback to @extension{AMD,query_buffer_object} @todo @extension{AMD,pinned_memory} "fallback" for @extension{ARB,buffer_storage} -%Extension | Status +Extension | Status ------------------------------------------- | ------ GLSL 4.40 | done @def_gl{MAX_VERTEX_ATTRIB_STRIDE} | | @@ -215,7 +215,7 @@ GLSL 4.40 | done @subsection opengl-support-45 OpenGL 4.5 -%Extension | Status +Extension | Status ------------------------------------------- | ------ GLSL 4.50 | done @extension{ARB,ES3_1_compatibility} | | @@ -232,7 +232,7 @@ GLSL 4.50 | done @subsection opengl-support-extensions ARB / Khronos OpenGL extensions -%Extension | Status +Extension | Status ------------------------------------------- | ------ @extension{ARB,robustness} | done @extension3{KHR,texture_compression_astc_ldr,texture_compression_astc_hdr} (also in ES) | | @@ -255,7 +255,7 @@ GLSL 4.50 | done @todo @extension{ATI,meminfo}, @extension{NVX,gpu_memory_info}, GPU temperature @todo @extension{AMD,performance_monitor}, @extension{INTEL,performance_query} -%Extension | Status +Extension | Status ------------------------------------------- | ------ @extension{AMD,vertex_shader_layer} | done (shading language only) @extension{AMD,shader_trinary_minmax} | done (shading language only) @@ -286,7 +286,7 @@ supported. ESSL 3.10 is supported. @subsection opengl-support-es30-extensions OpenGL ES 2.0 extensions to match ES 3.0 functionality -%Extension | Status +Extension | Status ------------------------------------------- | ------ @es_extension{ANGLE,framebuffer_blit} | done @es_extension{ANGLE,framebuffer_multisample} | done @@ -340,7 +340,7 @@ Only extensions not already listed in above tables are included here. @todo Support also IMG_multisampled_render_to_texture? It has different enum values (!) -%Extension | Status +Extension | Status ------------------------------------------- | ------ @es_extension{APPLE,texture_format_BGRA8888} | done @es_extension{CHROMIUM,map_sub} | only buffer mapping @@ -366,7 +366,7 @@ Only extensions not already listed in above tables are included here. @section opengl-unsupported Unsupported OpenGL features Some functionality, which is either soon-to-be deprecated or isn't proven to -add any performance gains, is not supported in %Magnum. See also +add any performance gains, is not supported in Magnum. See also @ref opengl-deprecated. @subsection opengl-unsupported-features Unsupported features @@ -376,7 +376,7 @@ add any performance gains, is not supported in %Magnum. See also not supported. The only exception are features that are needed for some OpenGL ES 2.0 implementations (such as luminance texture formats). - State queries (various `glIs*()`, `glGet*()` functions) are not supported. - %Magnum API is designed to prevent the need for majority of them, many of + Magnum API is designed to prevent the need for majority of them, many of them are tracked internally to avoid redundant state changes and in many cases it is easier to set the state to some value rather than query it and then decide on the result. For detailed state introspection please use diff --git a/doc/opengl.dox b/doc/opengl.dox index e3cacb0f8..10a3328dc 100644 --- a/doc/opengl.dox +++ b/doc/opengl.dox @@ -26,7 +26,7 @@ /** @page opengl OpenGL @brief State of OpenGL support, version and extension requirements. -The following table maps OpenGL function names to %Magnum API, useful for +The following table maps OpenGL function names to Magnum API, useful for developers with existing OpenGL background. Note that, as reverse mapping, each function documentation also contains list of OpenGL functions used. diff --git a/doc/platform.dox b/doc/platform.dox index b15efcf0b..aec3216ed 100644 --- a/doc/platform.dox +++ b/doc/platform.dox @@ -29,7 +29,7 @@ namespace Magnum { namespace Platform { - Next page: @ref types -@ref Platform namespace contains classes integrating %Magnum engine into +@ref Platform namespace contains classes integrating Magnum engine into various toolkits, both windowed and windowless. Each class has slightly different dependencies and platform requirements, see documentation of @ref Platform namespace and particular `*Application` classes for more @@ -55,7 +55,7 @@ use @ref MAGNUM_SDL2APPLICATION_MAIN() macro. To simplify the porting, the library provides `Platform::Application` typedef and `MAGNUM_APPLICATION_MAIN()` macro (but only if only one application header is included, to avoid ambiguity). Changing the code to use different toolkit is -then matter of replacing only the #`include` statement (and changing +then matter of replacing only the `#``include` statement (and changing one line in CMake build script, as you see later). Barebone application implementation which will just clear the window to dark @@ -125,7 +125,7 @@ void MyApplication::viewportEvent(const Vector2i& size) { Windowless applications provide just a context for ofscreen rendering or performing tasks on GPU. There is not yet any platform-independent toolkit which could handle this in portable way, thus you have to use platform-specific -ones. %Magnum provides windowless applications for X11-based Unix, OS X and +ones. Magnum provides windowless applications for X11-based Unix, OS X and Windows. To make things simple, as an example we will use only @ref Platform::WindowlessGlxApplication, see link for bootstrap application below for fully portable example. @@ -139,7 +139,7 @@ Similarly as with windowed applications, to simplify the porting, the library provides `Platform::WindowlessApplication` typedef and `MAGNUM_WINDOWLESSAPPLICATION_MAIN()` macro, but only if just one windowless application header is included. Changing the code to use different toolkit is then matter of replacing only the -#`include` statement. Aliases for windowless applications are +`#``include` statement. Aliases for windowless applications are separated from aliases for windowed applications, because projects commonly contain both graphics application and command-line tools (for data preparation etc.). @@ -182,8 +182,8 @@ MAGNUM_WINDOWLESSAPPLICATION_MAIN(MyApplication) @section platform-compilation Compilation with CMake -Barebone compilation consists just of finding %Magnum library with required -`*Application` component, adding %Magnum's `${MAGNUM_INCLUDE_DIRS}` and +Barebone compilation consists just of finding Magnum library with required +`*Application` component, adding Magnum's `${MAGNUM_INCLUDE_DIRS}` and application-specific `${MAGNUM_SDL2APPLICATION_INCLUDE_DIRS}` to include path, compilation of the executable and linking `${MAGNUM_LIBRARIES}` and `${MAGNUM_SDL2APPLICATION_LIBRARIES}` to it. @@ -194,7 +194,7 @@ and `${MAGNUM_APPLICATION_LIBRARIES}` aliases (or `${MAGNUM_WINDOWLESSAPPLICATIO only if only one application (windowless application) component is requested to avoid ambiguity. Changing the build script to use different toolkit is then matter of replacing only the requested `*Application` component (and one -#`include` line in the actual code, as said above). +`#``include` line in the actual code, as said above). @code find_package(Magnum REQUIRED Sdl2Application) @@ -263,7 +263,7 @@ MyApplication::MyApplication(int& argc, char** argv): Platform::Application(argc @section platform-custom Using custom platform toolkits In case you want to use some not-yet-supported toolkit or you don't want to use -the application wrappers in @ref Platform namespace, you can initialize %Magnum +the application wrappers in @ref Platform namespace, you can initialize Magnum manually. First create OpenGL context and then create instance of @ref Platform::Context class, which will take care of proper initialization and feature detection. The instance must be alive for whole application lifetime. diff --git a/doc/plugins.dox b/doc/plugins.dox index f2c3b0a8e..420f36794 100644 --- a/doc/plugins.dox +++ b/doc/plugins.dox @@ -25,12 +25,12 @@ namespace Magnum { /** @page plugins Loading and using plugins -@brief Extending %Magnum with additional functionality +@brief Extending Magnum with additional functionality - Previous page: @ref transformations - Next page: @ref scenegraph -The base %Magnum library contains math support, scene graph implementation and +The base Magnum library contains math support, scene graph implementation and is able to interact with graphics and audio hardware. However, the base library doesn't provide any functions for dealing with specific file formats, as there are simply too many formats to have them included directly in the library. @@ -52,7 +52,7 @@ might not be available on all platforms. @section plugins-types Plugin interfaces -%Magnum contains these plugin interfaces: +Magnum contains these plugin interfaces: - @ref Trade::AbstractImporter -- importers for general 2D and 3D scene, mesh, material, texture and image data. See `*Importer` classes in @@ -81,7 +81,7 @@ for given plugin interface, for example @ref Trade::AbstractImporter. You must set particular plugin directory, from which the manager will load and instantiate the plugins. To save you from hardcoding the value into your application source, the plugin directory is provided as `MAGNUM_PLUGINS_DIR` -CMake variable. The default is set to %Magnum install location, but you can +CMake variable. The default is set to Magnum install location, but you can change it through CMake to anything else. The `MAGNUM_PLUGINS_IMPORTER_DIR`, `MAGNUM_PLUGINS_IMAGECONVERTER_DIR`, `MAGNUM_PLUGINS_FONT_DIR`, `MAGNUM_PLUGINS_FONTCONVERTER_DIR`, `MAGNUM_PLUGINS_AUDIOIMPORTER_DIR` @@ -202,7 +202,7 @@ int main(int argc, char** argv) { @section plugins-develop Developing your own plugins See class documentation of particular plugin interfaces for more information -about subclassing. The %Corrade's @ref plugin-management "plugin management tutorial" +about subclassing. The Corrade's @ref plugin-management "plugin management tutorial" contains more information about plugin compilation and registering. If you want to develop a plugin which depends on another, you need to find the diff --git a/doc/portability.dox b/doc/portability.dox index ce9138c4b..506b9e254 100644 --- a/doc/portability.dox +++ b/doc/portability.dox @@ -31,7 +31,7 @@ namespace Magnum { @section portability-target Target-specific code -If %Magnum is compiled with e.g. OpenGL ES 2.0 support, some features present +If Magnum is compiled with e.g. OpenGL ES 2.0 support, some features present in desktop version are not available. It means that some classes, functions and enum values are simply not included in headers. It is designed this way to make porting easier -- it is better to fail at compile time on e.g. undefined @@ -60,10 +60,10 @@ also @ref requires-gl, @ref requires-gles20 and @ref requires-gles30. @section portability-compiler Compiler- and platform-specific code -%Magnum is attempting to be future-proof and as intuitive for users as +Magnum is attempting to be future-proof and as intuitive for users as possible. Many features from C++11 are used to simplify things and make them faster and more secure, but on the other hand it requires fairly recent -compiler with good enough support of the new standard. Currently %Magnum is +compiler with good enough support of the new standard. Currently Magnum is written with GCC 4.8 and Clang 3.1 in mind, but support for some other compilers is also available and handled by Corrade library. See @ref Corrade.h for more information. @@ -108,7 +108,7 @@ MAGNUM_ASSERT_EXTENSION_SUPPORTED(GL::ARB::geometry_shader4); @endcode Each class, function or enum value is marked accordingly if it needs specific -extension or specific OpenGL version. Various classes in %Magnum are taking +extension or specific OpenGL version. Various classes in Magnum are taking advantage of some extensions and enable faster code paths if given extension is available, but also have proper fallback when it's not, see for example @ref AbstractShaderProgram-performance-optimization "AbstractShaderProgram", @@ -117,7 +117,7 @@ available, but also have proper fallback when it's not, see for example @section portability-shaders Writing portable shaders -%Shaders are probably the most painful thing to port. There are many issues to +Shaders are probably the most painful thing to port. There are many issues to address - different shader syntax (`in`/`out` vs. `attribute` and `varying` etc.), explicit vs. implicit methods to specify vertex attribute, uniform and texture uniform locations, required precision qualifiers in OpenGL ES etc. diff --git a/doc/scenegraph.dox b/doc/scenegraph.dox index 3a410b60b..a145ed4d0 100644 --- a/doc/scenegraph.dox +++ b/doc/scenegraph.dox @@ -30,7 +30,7 @@ namespace Magnum { namespace SceneGraph { - Previous page: @ref plugins - Next page: @ref shapes -%Scene graph provides way to hiearchically manage your objects, their +Scene graph provides way to hiearchically manage your objects, their transformation, physics interaction, animation and rendering. The library is contained in @ref SceneGraph namespace, see its documentation for more information about building and usage with CMake. @@ -41,7 +41,7 @@ There are naturally many possible feature combinations (2D vs. 3D, different transformation representations, animated vs. static, object can have collision shape, participate in physics events, have forward vs. deferred rendering...) and to make everything possible without combinatiorial explosion and allow the -users to provide their own features, scene graph in %Magnum is composed of +users to provide their own features, scene graph in Magnum is composed of three main components: - objects, providing parent/children hierarchy @@ -63,7 +63,7 @@ is dimension count (2D or 3D) and underlying floating-point type. classes have convenience aliases so you don't have to explicitly specify it. -%Scene graph has implementation of transformations in both 2D and 3D, using +Scene graph has implementation of transformations in both 2D and 3D, using either matrices or combination of position and rotation. Each implementation has its own advantages and disadvantages -- for example when using matrices you can have nearly arbitrary transformations, but composing transformations @@ -76,11 +76,11 @@ needs, see source of other transformation classes for more information. @section scenegraph-hierarchy Scene hierarchy -%Scene hierarchy is skeleton part of scene graph. In the root there is +Scene hierarchy is skeleton part of scene graph. In the root there is @ref Scene and its children are @ref Object instances. The hierarchy has some transformation type, identical for all objects (because for example having part of the tree in 2D and part in 3D just wouldn't make sense). Common usage is to -typedef %Scene and %Object with desired transformation type to save unnecessary +typedef Scene and Object with desired transformation type to save unnecessary typing later: @code typedef SceneGraph::Scene Scene3D; @@ -89,7 +89,7 @@ typedef SceneGraph::Object Object3D; Then you can start building the hierarchy by *parenting* one object to another. Parent object can be either passed in constructor or using @ref Object::setParent(). -%Scene is always root object, so it naturally cannot have parent object. +Scene is always root object, so it naturally cannot have parent object. @code Scene3D scene; @@ -97,7 +97,7 @@ auto first = new Object3D(&scene); auto second = new Object3D(first); @endcode -%Object children can be accessed using @ref Object::firstChild() and +Object children can be accessed using @ref Object::firstChild() and @ref Object::lastChild(), then you can traverse siblings (objects with the same parent) with @ref Object::previousSibling() and @ref Object::nextSibling(). For example all children of an object can be traversed the following way: @@ -115,7 +115,7 @@ for information about possible issues. The object is derived from the transformation you specified earlier in the `typedef`, so you can directly transform the objects using methods of given -transformation implementation. %Scene, as a root object, cannot have any +transformation implementation. Scene, as a root object, cannot have any transformation. For convenience you can use method chaining: @code auto next = new Object3D; @@ -267,7 +267,7 @@ because `object` is created on stack. If this doesn't already crash, the When destroying the object, all its features are destroyed. For features added as member it's no issue, features added using multiple inheritance must be -inherited after the %Object class: +inherited after the Object class: @code class MyObject: public Object3D, MyFeature { public: diff --git a/doc/shapes.dox b/doc/shapes.dox index b52c0ed0b..664897de0 100644 --- a/doc/shapes.dox +++ b/doc/shapes.dox @@ -42,7 +42,7 @@ grouped together using various operations. @section shapes-collection Available shapes -%Magnum provides a set of simple shapes for collision detection, similarly to +Magnum provides a set of simple shapes for collision detection, similarly to what is found in many other collision detection libraries. Additionally some shapes are provided in inverted form -- e.g. inverted box detects collisions on outside instead of inside, which might be useful for example to create bounds @@ -55,7 +55,7 @@ around platformer game level. - @ref Shapes::LineSegment "Shapes::LineSegment*D" -- @copybrief Shapes::LineSegment Because of numerical instability it's not possible to detect collisions of -line and point. %Collision of two lines can be detected only in 2D. +line and point. Collision of two lines can be detected only in 2D. @subsection shapes-2D Two-dimensional shapes @@ -76,7 +76,7 @@ is least efficient. @section shapes-composition Creating shape compositions -%Shapes can be composed together using one of three available logical +Shapes can be composed together using one of three available logical operations: AND, OR and NOT. These operations are mapped to `&&`, `||` and `!` operators, so for example creating negation of logical OR of line segment and point is simple as this: @@ -110,7 +110,7 @@ Shapes::Composition3D composition = simplified && (sphere || box); @section shapes-collisions Detecting shape collisions -%Shape pairs which have collision occurence detection implemented can be tested +Shape pairs which have collision occurence detection implemented can be tested for collision using the `%` operator. The operator returns boolean describing whether the collision happened or not. Example: @code @@ -137,7 +137,7 @@ if(c) { @section shapes-scenegraph Integration with scene graph -%Shape can be attached to object in the scene using @ref Shapes::Shape feature. +Shape can be attached to object in the scene using @ref Shapes::Shape feature. In conjunction with @ref Shapes::ShapeGroup you can use @ref Shapes::Shape::collides() and @ref Shapes::Shape::collision() similarly to the `%` and `/` operators above. Please note that the shape group caches the diff --git a/doc/transformations.dox b/doc/transformations.dox index 97b81c0e4..b6d491223 100644 --- a/doc/transformations.dox +++ b/doc/transformations.dox @@ -37,7 +37,7 @@ with CMake. @tableofcontents -%Magnum provides classes for transformations in both 2D and 3D. Each class is +Magnum provides classes for transformations in both 2D and 3D. Each class is suited for different purposes, but their usage is nearly the same to make your life simpler. This page will explain the basic operation and differences between various representations. @@ -99,7 +99,7 @@ can be created by calling @ref Matrix4::rotation(), @ref Quaternion::rotation() or @ref DualQuaternion::rotation(). The axis must be always of unit length to avoid redundant normalization. Shortcuts @ref Vector3::xAxis(), @ref Vector3::yAxis() and @ref Vector3::zAxis() are provided for convenience. -%Matrix representation has also @ref Matrix4::rotationX(), +Matrix representation has also @ref Matrix4::rotationX(), @ref Matrix4::rotationY() and @ref Matrix4::rotationZ() which are faster than using the generic function for rotation around primary axes. Examples: @code @@ -197,7 +197,7 @@ auto b = Matrix4::translation(Vector3::yAxis(5.0f))* Inverse transformation can be computed using @ref Matrix3::inverted(), @ref Matrix4::inverted(), @ref Complex::inverted(), @ref Quaternion::inverted(), -@ref DualComplex::inverted() or @ref DualQuaternion::inverted(). %Matrix +@ref DualComplex::inverted() or @ref DualQuaternion::inverted(). Matrix inversion is quite costly, so if your transformation involves only translation and rotation, you can use faster alternatives @ref Matrix3::invertedRigid() and @ref Matrix4::invertedRigid(). If you are sure that the (dual) complex number @@ -209,7 +209,7 @@ because it doesn't need to renormalize the result. @section transformations-transforming Transforming vectors and points Transformations can be used directly for transforming vectors and points. -%Vector transformation does not involve translation, in 2D can be done using +Vector transformation does not involve translation, in 2D can be done using @ref Matrix3::transformVector() and @ref Complex::transformVector(), in 3D using @ref Matrix4::transformVector() and @ref Quaternion::transformVector(). For transformation with normalized quaternion you can use faster alternative @@ -255,7 +255,7 @@ parts: Matrix3 c = Matrix3::from(rotation, {1.0f, 3.0f}); @endcode -%Complex numbers and quaternions are far better in this regard and they allow +Complex numbers and quaternions are far better in this regard and they allow you to extract rotation angle using @ref Complex::angle() or @ref Quaternion::angle() or rotation axis in 3D using @ref Quaternion::axis(). Their dual versions allow to extract both rotation and translation part using diff --git a/doc/troubleshooting.dox b/doc/troubleshooting.dox index 08aaeae5f..e68272bd4 100644 --- a/doc/troubleshooting.dox +++ b/doc/troubleshooting.dox @@ -30,13 +30,13 @@ namespace Magnum { @section troubleshooting-building Building issues -If your project suddenly stops building after %Magnum upgrade, check these +If your project suddenly stops building after Magnum upgrade, check these things: - If the building fails on CMake step, be sure that you have up-to-date `FindCorrade.cmake`, `FindMagnum.cmake` and other CMake modules in your project (`FindSDL2.cmake`). They are contained in `modules/` directory of - %Magnum sources (and sources of other projects) also are installed into + Magnum sources (and sources of other projects) also are installed into `share/cmake/Magnum`. - In some cases when the changes done to build system are too drastic, recreating the build dir or clearing CMake cache is needed, but this is diff --git a/doc/types.dox b/doc/types.dox index 027c89e66..b19dcaf80 100644 --- a/doc/types.dox +++ b/doc/types.dox @@ -35,12 +35,12 @@ its documentation for more information about usage with CMake. @section types-builtin Builtin types -%Magnum provides typedefs for builtin integral and floating-point arithmetic +Magnum provides typedefs for builtin integral and floating-point arithmetic types to ensure portability (e.g. @ref Int is *always* 32bit), maintain consistency and reduce confusion (e.g. `std::int32_t`, `int` and `GLint` all refer to the same type). -| %Magnum type | Size | Equivalent GLSL type | +| Magnum type | Size | Equivalent GLSL type | | ------------------ | -------------- | -------------------- | | @ref UnsignedByte | 8bit unsigned | | | @ref Byte | 8bit signed | | @@ -65,14 +65,14 @@ underlying type. @section types-matrix Matrix/vector types -| %Magnum vector type | Equivalent GLSL type | +| Magnum vector type | Equivalent GLSL type | | ---------------------------------------------- | ------------------------- | | @ref Vector2, @ref Vector3, @ref Vector4 | `vec2`, `vec3`, `vec4` | | @ref Vector2ui, @ref Vector3ui, @ref Vector4ui | `uvec2`, `uvec3`, `uvec4` | | @ref Vector2i, @ref Vector3i, @ref Vector4i | `ivec2`, `ivec3`, `ivec4` | | @ref Vector2d, @ref Vector3d, @ref Vector4d | `dvec2`, `dvec3`, `dvec4` | -| %Magnum matrix type | Equivalent GLSL type | +| Magnum matrix type | Equivalent GLSL type | | ---------------------------------------------------------------- | ------------------------------------ | | @ref Matrix2x2 or @ref Matrix2x2d | `mat2`/`mat2x2` or `dmat2`/`dmat2x2` | | @ref Matrix3 / @ref Matrix3x3 or @ref Matrix3d / @ref Matrix3x3d | `mat3`/`mat3x3` or `dmat3`/`dmat3x3` | @@ -103,7 +103,7 @@ to the internal data array. @section types-special Special types -%Magnum has special type for strongly-typed representation of angles, namely +Magnum has special type for strongly-typed representation of angles, namely the @ref Deg and @ref Rad classes (or @ref Degd and @ref Radd with @ref Double as underlying type). Their only purpose is to avoid common degree-vs-radian bugs (i.e. entering degree value where radians should be) and make the