diff --git a/doc/building.dox b/doc/building.dox index df562d963..e8bb33d3a 100644 --- a/doc/building.dox +++ b/doc/building.dox @@ -122,17 +122,19 @@ 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_XEGLAPPLICATION` - @ref Platform::XEglApplication "XEglApplication", - available only if targeting OpenGL ES (see above). Requires **X11** and - **EGL** libraries. - - `WITH_GLXAPPLICATION` - @ref Platform::GlxApplication "GlxApplication". - Requires **X11** and **GLX** libraries. - - `WITH_WINDOWLESSGLXAPPLICATION` - @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication". - Requires **X11** and **GLX** libraries. - - `WITH_GLUTAPPLICATION` - @ref Platform::GlutApplication "GlutApplication", - available only if targeting desktop OpenGL. Requires **GLUT** library. - - `WITH_SDL2APPLICATION` - @ref Platform::Sdl2Application "Sdl2Application". - Requires **SDL2** library. +- `WITH_GLUTAPPLICATION` - @ref Platform::GlutApplication "GlutApplication", + available only if targeting desktop OpenGL. Requires **GLUT** library. +- `WITH_GLXAPPLICATION` - @ref Platform::GlxApplication "GlxApplication". + Requires **X11** and **GLX** libraries. +- `WITH_NACLAPPLICATION` - @ref Platform::NaClApplication "NaClApplication", + available only if targeting Google Chrome Native Client (see below). +- `WITH_SDL2APPLICATION` - @ref Platform::Sdl2Application "Sdl2Application". + Requires **SDL2** library. +- `WITH_XEGLAPPLICATION` - @ref Platform::XEglApplication "XEglApplication", + available only if targeting OpenGL ES (see above). Requires **X11** and + **EGL** libraries. +- `WITH_WINDOWLESSGLXAPPLICATION` - @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication". + Requires **X11** and **GLX** libraries. @subsection building-tests Building and running unit tests diff --git a/doc/cmake.dox b/doc/cmake.dox new file mode 100644 index 000000000..6c3bcd853 --- /dev/null +++ b/doc/cmake.dox @@ -0,0 +1,110 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013 Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +namespace Magnum { +/** @page cmake Usage with CMake +@brief Guide how to find and use %Magnum with CMake build system + +%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 (and its dependencies) +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 the system. + +Basic usage is: + + find_package(Magnum REQUIRED) + +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_INCLUDE_DIRS` -- Root include dir and include dirs of dependencies +- `MAGNUM_PLUGINS_IMPORTER_DIR` -- Directory with importer plugins + +However, this command will try to find only the base library, not the optional +components. The base library depends on %Corrade, OpenGL and GLEW libraries (or +OpenGL ES libraries). Additional dependencies are specified by the components. +The optional components are: + +- `%DebugTools` -- DebugTools library (depends on `%MeshTools`, `%Physics`, + `%Primitives`, `%SceneGraph` and `%Shaders` components) +- `%MeshTools` -- MeshTools library +- `%Physics` -- Physics library (depends on `%SceneGraph` component) +- `%Primitives` -- Primitives library +- `%SceneGraph` -- SceneGraph library +- `%Shaders` -- Shaders library +- `%Text` -- Text library (depends on `%TextureTools` component, FreeType + library and possibly HarfBuzz library, see below) +- `%TextureTools` -- TextureTools library + +Platform namespace is split into more components: + +- `%GlutApplication` -- @ref Platform::GlutApplication "GlutApplication" + (depends on GLUT library) +- `%GlxApplication` -- @ref Platform::GlxApplication "GlxApplication" (depends + on GLX and X11 libraries) +- `%NaClApplication` -- @ref Platform::NaClApplication "NaClApplication" + (only if targeting Google Chrome Native Client) +- `%Sdl2Application` -- @ref Platform::Sdl2Application "Sdl2Application" + (depends on SDL2 library) +- `%XEglApplication` -- @ref Platform::XEglApplication "XEglApplication" + (depends on EGL and X11 libraries) +- `%WindowlessGlxApplication` -- @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication" + (depends on GLX and X11 libraries) + +Example usage with specifying additional components is: + + find_package(Magnum REQUIRED MeshTools Primitives GlutApplication) + +For each component is then defined: + +- `MAGNUM_*_FOUND` -- Whether the component was found +- `MAGNUM_*_LIBRARIES` -- Component library and dependent libraries +- `MAGNUM_*_INCLUDE_DIRS` -- Include dirs of module dependencies + +If exactly one `*Application` or exactly one `Windowless*Application` component +is requested and found, its libraries and include dirs are available in +convenience aliases `MAGNUM_APPLICATION_LIBRARIES` / +`MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES` and `MAGNUM_APPLICATION_INCLUDE_DIRS` +/ `MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS` to simplify porting. + +Features of found %Magnum library are exposed in these CMake variables, they +are also available as preprocessor variables if including Magnum.h: + +- `MAGNUM_TARGET_GLES` -- Defined if compiled for OpenGL ES +- `MAGNUM_TARGET_GLES2` -- Defined if compiled for OpenGL ES 2.0 +- `MAGNUM_TARGET_DESKTOP_GLES` -- Defined if compiled with OpenGL ES emulation + on desktop OpenGL +- `MAGNUM_TARGET_NACL` -- Defined if compiled for Google Chrome Native Client +- `MAGNUM_USE_HARFBUZZ` -- Defined if HarfBuzz library is used for text + rendering + +%Corrade library provides also its own set of CMake macros and variables, see +@ref corrade-cmake "its documentation" for more information. + +*/ +} diff --git a/doc/namespaces.dox b/doc/namespaces.dox index 3fd741cb4..e60a77c03 100644 --- a/doc/namespaces.dox +++ b/doc/namespaces.dox @@ -32,6 +32,9 @@ @brief Root namespace Contains classes for interacting with OpenGL. + +This library is built by default and found by default in CMake. See +@ref building and @ref cmake for more information. */ /** @dir Platform @@ -42,6 +45,10 @@ Contains classes for interacting with OpenGL. Base classes for creating applications with various toolkits. See @ref platform for introduction. + +Parts of this namespace are built when `WITH_*APPLICATION` is enabled and found +as `*Application` component in CMake. See @ref building and @ref cmake for more +information. */ /** @dir Math @@ -52,6 +59,9 @@ for introduction. Template classes for matrix and vector calculations. See @ref matrix-vector and @ref transformations for introduction. + +This library is built by default and found by default in CMake. See +@ref building and @ref cmake for more information. */ /** @dir Math/Algorithms @@ -61,6 +71,9 @@ and @ref transformations for introduction. @brief %Algorithms Various matrix and vector algorithms. + +This library is built by default and found by default in CMake. See +@ref building and @ref cmake for more information. */ /** @dir Math/Geometry @@ -70,6 +83,9 @@ Various matrix and vector algorithms. @brief %Geometry library Functions for computing intersections, distances, areas and volumes. + +This library is built by default and found by default in CMake. See +@ref building and @ref cmake for more information. */ /** @dir DebugTools @@ -80,6 +96,10 @@ Functions for computing intersections, distances, areas and volumes. Debugging helpers, renderers and profilers. See @ref debug-tools for introduction. + +This library is built when `WITH_DEBUGTOOLS` is enabled and found as +`%DebugTools` component in CMake. See @ref building and @ref cmake for more +information. */ /** @dir MeshTools @@ -89,6 +109,10 @@ introduction. @brief %Mesh tools Tools for generating, optimizing and cleaning meshes. + +This library is built when `WITH_MESHTOOLS` is enabled and found as +`%MeshTools` component in CMake. See @ref building and @ref cmake for more +information. */ /** @dir Primitives @@ -98,6 +122,10 @@ Tools for generating, optimizing and cleaning meshes. @brief Primitive library Basic primitives for testing purposes. + +This library is built when `WITH_PRIMITIVES` is enabled and found as +`%Primitives` component in CMake. See @ref building and @ref cmake for more +information. */ /** @dir SceneGraph @@ -109,6 +137,10 @@ Basic primitives for testing purposes. Managing object hierarchy, transformations and interactions. See @ref scenegraph for introduction. + +This library is built when `WITH_SCENEGRAPH` is enabled and found as +`%SceneGraph` component in CMake. See @ref building and @ref cmake for more +information. */ /** @dir Shaders @@ -118,6 +150,9 @@ Managing object hierarchy, transformations and interactions. See @brief Sample shaders Collection of shaders for testing purposes. + +This library is built when `WITH_SHADERS` is enabled and found as `%Shaders` +component in CMake. See @ref building and @ref cmake for more information. */ /** @dir Physics @@ -128,6 +163,9 @@ Collection of shaders for testing purposes. Collision detection system and rigid body objects. See @ref collision-detection for introduction. + +This library is built when `WITH_PHYSICS` is enabled and found as `%Physics` +component in CMake. See @ref building and @ref cmake for more information. */ /** @dir Text @@ -137,6 +175,9 @@ for introduction. @brief %Text rendering Font texture creation and text layouting. + +This library is built when `WITH_TEXT` is enabled and found as `%Text` +component in CMake. See @ref building and @ref cmake for more information. */ /** @dir TextureTools @@ -146,6 +187,10 @@ Font texture creation and text layouting. @brief %Texture tools Tools for generating, compressing and optimizing textures. + +This library is built when `WITH_TEXTURETOOLS` is enabled and found as +`%TextureTools` component in CMake. See @ref building and @ref cmake for more +information. */ /** @dir Trade @@ -156,4 +201,7 @@ Tools for generating, compressing and optimizing textures. Contains plugin interfaces for importing data of various formats and classes for direct access to the data. + +This library is built by default and found by default in CMake. See +@ref building and @ref cmake for more information. */ diff --git a/doc/portability.dox b/doc/portability.dox index b8f7082c8..b0ef9fd3e 100644 --- a/doc/portability.dox +++ b/doc/portability.dox @@ -39,9 +39,11 @@ format is not supported. If you include Magnum.h, you get these predefined macros: - - `MAGNUM_TARGET_GLES` if targetting OpenGL ES 2.0 or 3.0 - - `MAGNUM_TARGET_GLES2` if targetting OpenGL ES 2.0 - - `MAGNUM_TARGET_NACL` if targetting Google Chrome Native Client +- @ref MAGNUM_TARGET_GLES_ "MAGNUM_TARGET_GLES" if targeting OpenGL ES 2.0 or + 3.0 +- @ref MAGNUM_TARGET_GLES2_ "MAGNUM_TARGET_GLES2" if targeting OpenGL ES 2.0 +- @ref MAGNUM_TARGET_NACL_ "MAGNUM_TARGET_NACL" if targeting Google Chrome + Native Client Example usage: @code @@ -63,12 +65,8 @@ 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 written with GCC 4.7 and Clang 3.1 in mind, but support for some other -compilers is also available: - - - GCC 4.6 support can be explicitly enabled with CMake option - `MAGNUM_GCC46_COMPATIBILITY` - -The options are also available as predefined macros when including Magnum.h. +compilers is also available and handled by Corrade library. See Corrade.h for +more information. Each feature is marked accordingly if it is not available on some compilers, see @ref SceneGraph::DrawableGroup3D for an example. It is up to you (or your diff --git a/doc/required-extensions.dox b/doc/required-extensions.dox index 554359a1f..610e4542b 100644 --- a/doc/required-extensions.dox +++ b/doc/required-extensions.dox @@ -27,8 +27,10 @@ The engine is meant to be run on OpenGL 3 capable hardware, but most of the functionality is working in OpenGL 2.1 hardware too (i.e. integrated Intel -GPUs), unless stated otherwise. OpenGL ES is also supported, see @ref building -for guide how to build the engine for it. +GPUs), unless stated otherwise. OpenGL ES is also supported. + +@see @ref building, @ref cmake, @ref MAGNUM_TARGET_GLES_ "MAGNUM_TARGET_GLES", + @ref MAGNUM_TARGET_GLES2_ "MAGNUM_TARGET_GLES2" Following are lists of functionality requiring specific OpenGL version. In most cases it is also specified which extension is required for given @@ -51,6 +53,8 @@ supported on Intel GPUs even if they are capable of OpenGL 2.1 only). - @subpage unsupported @page requires-gl Functionality requiring desktop OpenGL (not available on OpenGL ES) +@see @ref MAGNUM_TARGET_GLES_ "MAGNUM_TARGET_GLES" + @page requires-gl30 Functionality requiring OpenGL 3.0 @page requires-gl31 Functionality requiring OpenGL 3.1 @page requires-gl32 Functionality requiring OpenGL 3.2 @@ -59,8 +63,13 @@ supported on Intel GPUs even if they are capable of OpenGL 2.1 only). @page requires-gl41 Functionality requiring OpenGL 4.1 @page requires-gl42 Functionality requiring OpenGL 4.2 @page requires-gl43 Functionality requiring OpenGL 4.3 + @page requires-extension Functionality requiring specific OpenGL extension + @page requires-gles30 Functionality requiring OpenGL ES 3.0 +@see @ref MAGNUM_TARGET_GLES2_ "MAGNUM_TARGET_GLES2" + @page requires-es-extension Functionality requiring specific OpenGL ES extension +@see @ref MAGNUM_TARGET_GLES2_ "MAGNUM_TARGET_GLES2" */ diff --git a/modules/FindMagnum.cmake b/modules/FindMagnum.cmake index d779170e8..509e806e5 100644 --- a/modules/FindMagnum.cmake +++ b/modules/FindMagnum.cmake @@ -2,11 +2,8 @@ # # Basic usage: # find_package(Magnum [REQUIRED]) -# This command tries to find Magnum library and then defines: -# MAGNUM_FOUND - Whether the library was found -# MAGNUM_TARGET_GLES - Defined if Magnum was built for OpenGL -# ES, slightly reducing feature count. The same variable is also -# #defined in Magnum headers. +# This command tries to find base Magnum library and then defines: +# MAGNUM_FOUND - Whether the base library was found # MAGNUM_LIBRARIES - Magnum library and dependent libraries # MAGNUM_INCLUDE_DIRS - Root include dir and include dirs of # dependencies @@ -18,22 +15,22 @@ # DebugTools - DebugTools library (depends on MeshTools, Physics, # Primitives, SceneGraph and Shaders components) # MeshTools - MeshTools library -# Physics - Physics library -# Primitives - Library with stock geometric primitives (static) -# SceneGraph - Scene graph library -# Shaders - Library with stock shaders -# Text - Text rendering library (depends on TextureTools -# component, FreeType library and possibly HarfBuzz -# library, see below) +# Physics - Physics library (depends on SceneGraph component) +# Primitives - Primitives library +# SceneGraph - SceneGraph library +# Shaders - Shaders library +# Text - Text library (depends on TextureTools component, +# FreeType library and possibly HarfBuzz library, +# see below) # TextureTools - TextureTools library -# GlxApplication - GLX application (depends on X11 libraries) -# XEglApplication - X/EGL application (depends on EGL and X11 libraries) -# WindowlessGlxApplication - Windowless GLX application (depends on X11 -# libraries) # GlutApplication - GLUT application (depends on GLUT library) -# Sdl2Application - SDL2 application (depends on SDL2 library) -# NaClApplication - NaCl application (only if targetting Google Chrome +# GlxApplication - GLX application (depends on GLX and X11 libraries) +# NaClApplication - NaCl application (only if targeting Google Chrome # Native Client) +# Sdl2Application - SDL2 application (depends on SDL2 library) +# XEglApplication - X/EGL application (depends on EGL and X11 libraries) +# WindowlessGlxApplication - Windowless GLX application (depends on GLX +# and X11 libraries) # Example usage with specifying additional components is: # find_package(Magnum [REQUIRED|COMPONENTS] # MeshTools Primitives GlutApplication) @@ -43,9 +40,9 @@ # MAGNUM_*_INCLUDE_DIRS - Include dirs of module dependencies # If exactly one *Application or exactly one Windowless*Application # component is requested and found, its libraries and include dirs are -# available in convenience aliases MAGNUM_APPLICATION_LIBRARIES or +# available in convenience aliases MAGNUM_APPLICATION_LIBRARIES / # MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES and MAGNUM_APPLICATION_INCLUDE_DIRS -# or MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS to simplify porting. +# / MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS to simplify porting. # # Features of found Magnum library are exposed in these variables: # MAGNUM_TARGET_GLES - Defined if compiled for OpenGL ES diff --git a/src/Extensions.h b/src/Extensions.h index d1fdf312b..de1d5c285 100644 --- a/src/Extensions.h +++ b/src/Extensions.h @@ -41,6 +41,9 @@ the same public methods as Extension class (requiredVersion(), coreVersion() and string(), but these structs are better suited for compile-time decisions rather than %Extension instances. See Context::isExtensionSupported() for example usage. + +This namespace is built by default and found by default in CMake. See +@ref building and @ref cmake for more information. @see MAGNUM_ASSERT_EXTENSION_SUPPORTED() @todo Manual indices for extensions, this has gaps */ diff --git a/src/Magnum.h b/src/Magnum.h index b443cf30a..c597594a1 100644 --- a/src/Magnum.h +++ b/src/Magnum.h @@ -65,6 +65,63 @@ using Corrade::Utility::Warning; using Corrade::Utility::Error; #endif +#ifdef DOXYGEN_GENERATING_OUTPUT + +/** @todoc remove trailing underscores when Doxygen can handle `undef` */ + +/** +@brief OpenGL ES target + +`MAGNUM_TARGET_GLES` is defined if the engine is built for OpenGL ES 3.0 or +OpenGL ES 2.0. +@see @ref MAGNUM_TARGET_GLES_ "MAGNUM_TARGET_GLES", + @ref MAGNUM_TARGET_DESKTOP_GLES_ "MAGNUM_TARGET_DESKTOP_GLES", + @ref MAGNUM_TARGET_NACL_ "MAGNUM_TARGET_NACL", @ref building +*/ +#define MAGNUM_TARGET_GLES_ + +/** +@brief OpenGL ES 2.0 target. + +`MAGNUM_TARGET_GLES2` is defined if the engine is built for OpenGL ES 2.0. +Implies also @ref MAGNUM_TARGET_GLES_ "MAGNUM_TARGET_GLES". +@see @ref MAGNUM_TARGET_DESKTOP_GLES_ "MAGNUM_TARGET_DESKTOP_GLES", + @ref MAGNUM_TARGET_NACL_ "MAGNUM_TARGET_NACL", @ref building +*/ +#define MAGNUM_TARGET_GLES2_ + +/** +@brief Desktop emulation of OpenGL ES target + +`MAGNUM_TARGET_DESKTOP_GLES` is defined if the engine is built for OpenGL ES +3.0 or OpenGL ES 2.0 emulated within standard desktop OpenGL. Implies also +@ref MAGNUM_TARGET_GLES_ "MAGNUM_TARGET_GLES". +@see @ref MAGNUM_TARGET_GLES2_ "MAGNUM_TARGET_GLES2", + @ref MAGNUM_TARGET_NACL_ "MAGNUM_TARGET_NACL", @ref building +*/ +#define MAGNUM_TARGET_DESKTOP_GLES_ + +/** +@brief Google Chrome Native Client target + +`MAGNUM_TARGET_NACL` is defined if the engine is built for OpenGL ES 2.0 on +Google Chrome Native Client. Implies also @ref MAGNUM_TARGET_GLES_ "MAGNUM_TARGET_GLES" +and @ref MAGNUM_TARGET_GLES2_ "MAGNUM_TARGET_GLES". +@see @ref building +*/ +#define MAGNUM_TARGET_NACL_ + +/** +@brief HarfBuzz library usage + +`MAGNUM_USE_HARFBUZZ` is defined if HarfBuzz library is used for text +rendering. +@see Text::HarfBuzzFont +*/ +#define MAGNUM_USE_HARFBUZZ_ + +#endif + /** @{ @name Basic type definitions See @ref types for more information.