Documented CMake usage and preprocessor variables.

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",
+- `WITH_GLUTAPPLICATION` - @ref Platform::GlutApplication "GlutApplication",
-   available only if targeting OpenGL ES (see above). Requires **X11** and
+  available only if targeting desktop OpenGL. Requires **GLUT** library.
-   **EGL** libraries.
+- `WITH_GLXAPPLICATION` - @ref Platform::GlxApplication "GlxApplication".
- - `WITH_GLXAPPLICATION` - @ref Platform::GlxApplication "GlxApplication".
+  Requires **X11** and **GLX** libraries.
-   Requires **X11** and **GLX** libraries.
+- `WITH_NACLAPPLICATION` - @ref Platform::NaClApplication "NaClApplication",
- - `WITH_WINDOWLESSGLXAPPLICATION` - @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication".
+  available only if targeting Google Chrome Native Client (see below).
-   Requires **X11** and **GLX** libraries.
+- `WITH_SDL2APPLICATION` - @ref Platform::Sdl2Application "Sdl2Application".
- - `WITH_GLUTAPPLICATION` - @ref Platform::GlutApplication "GlutApplication",
+  Requires **SDL2** library.
-   available only if targeting desktop OpenGL. Requires **GLUT** library.
+- `WITH_XEGLAPPLICATION` - @ref Platform::XEglApplication "XEglApplication",
- - `WITH_SDL2APPLICATION` - @ref Platform::Sdl2Application "Sdl2Application".
+  available only if targeting OpenGL ES (see above). Requires **X11** and
-   Requires **SDL2** library.
+  **EGL** libraries.
+- `WITH_WINDOWLESSGLXAPPLICATION` - @ref Platform::WindowlessGlxApplication "WindowlessGlxApplication".
+  Requires **X11** and **GLX** libraries.
 
 @subsection building-tests Building and running unit tests
 

doc/cmake.dox

@@ -0,0 +1,110 @@
+/*
+    This file is part of Magnum.
+
+    Copyright © 2010, 2011, 2012, 2013 Vladimír Vondruš <mosra@centrum.cz>
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included
+    in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+*/
+
+namespace Magnum {
+/** @page 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.
+
+*/
+}

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.
 */

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
+- @ref MAGNUM_TARGET_GLES_ "MAGNUM_TARGET_GLES" if targeting OpenGL ES 2.0 or
- - `MAGNUM_TARGET_GLES2` if targetting OpenGL ES 2.0
+  3.0
- - `MAGNUM_TARGET_NACL` if targetting Google Chrome Native Client
+- @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:
+compilers is also available and handled by Corrade library. See Corrade.h for
-
+more information.
- - 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.
 
 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

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
+GPUs), unless stated otherwise. OpenGL ES is also supported.
-for guide how to build the engine for it.
+
+@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"
 
 */

modules/FindMagnum.cmake

@@ -2,11 +2,8 @@
 #
 # Basic usage:
 #  find_package(Magnum [REQUIRED])
-# This command tries to find Magnum library and then defines:
+# This command tries to find base Magnum library and then defines:
-#  MAGNUM_FOUND                 - Whether the library was found
+#  MAGNUM_FOUND                 - Whether the base 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.
 #  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
+#  Physics          - Physics library (depends on SceneGraph component)
-#  Primitives       - Library with stock geometric primitives (static)
+#  Primitives       - Primitives library
-#  SceneGraph       - Scene graph library
+#  SceneGraph       - SceneGraph library
-#  Shaders          - Library with stock shaders
+#  Shaders          - Shaders library
-#  Text             - Text rendering library (depends on TextureTools
+#  Text             - Text library (depends on TextureTools component,
-#                     component, FreeType library and possibly HarfBuzz
+#                     FreeType library and possibly HarfBuzz library,
-#                     library, see below)
+#                     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)
+#  GlxApplication   - GLX application (depends on GLX and X11 libraries)
-#  NaClApplication  - NaCl application (only if targetting Google Chrome
+#  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

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
 */

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.