doc: documented all command-line utilities.

doc/utilities.dox

@@ -0,0 +1,35 @@
+/*
+    This file is part of Magnum.
+
+    Copyright © 2010, 2011, 2012, 2013, 2014
+              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 utilities Utilities
+@brief Command-line utilities for system information and data conversion
+
+-   @subpage magnum-info -- @copybrief magnum-info
+-   @subpage magnum-distancefieldconverter -- @copybrief magnum-distancefieldconverter
+-   @subpage magnum-fontconverter -- @copybrief magnum-fontconverter
+
+*/
+}

src/Magnum/Platform/magnum-info.cpp

@@ -64,6 +64,61 @@
 
 namespace Magnum {
 
+/** @page magnum-info Magnum Info
+@brief Displays information about %Magnum engine and OpenGL capabilities
+
+@section magnum-info-usage Usage
+
+    magnum-info [-h|--help] [--all-extensions] [--limits]
+
+Arguments:
+
+-   ` -h`, `--help` -- display this help message and exit
+-   `--all-extensions` -- show extensions also for fully supported versions
+-   `--limits` -- display also limits and implementation-defined values
+
+@section magnum-info-example Example output
+
+      +---------------------------------------------------------+
+      | Information about Magnum engine and OpenGL capabilities |
+      +---------------------------------------------------------+
+
+    Used application: Platform::WindowlessGlxApplication
+    Compilation flags:
+        CORRADE_BUILD_DEPRECATED
+        MAGNUM_BUILD_DEPRECATED
+
+    Vendor: NVIDIA Corporation
+    Renderer: GeForce GT 740M/PCIe/SSE2
+    OpenGL version: OpenGL 4.4 (4.4.0 NVIDIA 337.25)
+    Context flags:
+    Supported GLSL versions:
+        440 core
+        430 core
+        420 core
+        410 core
+        400 core
+        330 core
+        310 es
+        300 es
+        100
+
+    Vendor extension support:
+        GL_AMD_vertex_shader_layer                                        -
+        GL_AMD_shader_trinary_minmax                                      -
+        GL_ARB_robustness                                             SUPPORTED
+        GL_ATI_texture_mirror_once                                    SUPPORTED
+        GL_EXT_texture_filter_anisotropic                             SUPPORTED
+        GL_EXT_texture_mirror_clamp                                   SUPPORTED
+        GL_EXT_direct_state_access                                    SUPPORTED
+        GL_EXT_texture_sRGB_decode                                    SUPPORTED
+        GL_EXT_shader_integer_mix                                     SUPPORTED
+        GL_EXT_debug_label                                                -
+        GL_EXT_debug_marker                                               -
+        GL_GREMEDY_string_marker                                          -
+
+*/
+
 class MagnumInfo: public Platform::WindowlessApplication {
     public:
         explicit MagnumInfo(const Arguments& arguments);

src/Magnum/Text/AbstractFontConverter.h

@@ -45,6 +45,9 @@ Provides functionality for converting arbitrary font to different format. See
 @ref plugins for more information and `*FontConverter` classes in @ref Text
 namespace for available font converter plugins.
 
+You can use the @ref magnum-fontconverter "magnum-fontconverter" utility to do
+font conversion on command-line.
+
 ## Subclassing
 
 Plugin implements @ref doFeatures() and one or more of `exportTo*()` /

src/Magnum/Text/fontconverter.cpp

@@ -44,7 +44,50 @@
 
 #include "fontconverterConfigure.h"
 
-namespace Magnum { namespace Text {
+namespace Magnum {
+
+/**
+@page magnum-fontconverter Font conversion utility
+@brief Converts font to raster one of given atlas size
+
+@section magnum-fontconverter-usage Usage
+
+    magnum-fontconverter [-h|--help] --font FONT --converter CONVERTER [--plugin-dir DIR] [--characters CHARACTERS] [--font-size N] [--atlas-size "X Y"] [--output-size "X Y"] [--radius N] [--] input output
+
+Arguments:
+
+-   `input` -- input font
+-   `output` -- output filename prefix
+-   `-h`, `--help` -- display help message and exit
+-   `--font FONT` -- font plugin
+-   `--converter CONVERTER` -- font converter plugin
+-   `--plugin-dir DIR` -- base plugin dir (defaults to plugin directory in
+    %Magnum install location)
+-   `--characters CHARACTERS` -- characters to include in the output (default:
+    `abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789?!:,. `)
+-   `--font-size N` -- input font size (default: `128`)
+-   `--atlas-size "X Y"` -- glyph atlas size (default: `"2048 2048"`)
+-   `--output-size "X Y"` -- output atlas size. If set to zero size, distance
+    field computation will not be used. (default: `"256 256"`)
+-   `--radius N` -- distance field computation radius (default: `24`)
+
+The resulting font files can be then used as specified in the documentation of
+`converter` plugin.
+
+@section magnum-fontconverter-example Example usage
+
+Making raster font from TTF file with default set of characters using
+@ref Text::FreeTypeFont "FreeTypeFont" font plugin and
+@ref Text::MagnumFontConverter "MagnumFontConverter" converter plugin:
+
+    magnum-fontconverter --font FreeTypeFont --converter MagnumFontConverter DejaVuSans.ttf myfont
+
+According to `MagnumFontConverter` plugin documentation, this will generate
+files `myfont.conf` and `myfont.tga` in current directory. You can then load
+and use them with the @ref Text::MagnumFont "MagnumFont" plugin.
+*/
+
+namespace Text {
 
 class FontConverter: public Platform::WindowlessApplication {
     public:
@@ -130,6 +173,8 @@ int FontConverter::exec() {
     return 0;
 }
 
-}}
+}
+
+}
 
 MAGNUM_WINDOWLESSAPPLICATION_MAIN(Magnum::Text::FontConverter)

src/Magnum/TextureTools/DistanceField.h

@@ -56,6 +56,11 @@ less memory and can be scaled without aliasing issues. Additionally it provides
 foundation for features like outlining, glow or drop shadow essentially for
 free.
 
+You can also use the @ref magnum-distancefieldconverter "magnum-distancefieldconverter"
+utility to do distance field conversion on command-line. By extension, this
+functionality is also provided through @ref magnum-fontconverter "magnum-fontconverter"
+utility.
+
 ### The algorithm
 
 For each pixel inside @p rectangle the algorithm looks at corresponding pixel in

src/Magnum/TextureTools/distancefieldconverter.cpp

@@ -50,7 +50,42 @@
 
 #include "distancefieldconverterConfigure.h"
 
-namespace Magnum { namespace TextureTools {
+namespace Magnum {
+
+/** @page magnum-distancefieldconverter Distance Field conversion utility
+@brief Converts black&white image to distance field representation
+
+@section magnum-distancefieldconverter-usage Usage
+
+    magnum-distancefieldconverter [-h|--help] [--importer IMPORTER] [--converter CONVERTER] [--plugin-dir DIR] --output-size "X Y" --radius N [--] input output
+
+Arguments:
+
+-   `input` -- input image
+-   `output` -- output image
+-   `-h`, `--help` -- display help message and exit
+-   `--importer IMPORTER` -- image importer plugin (default: @ref Trade::TgaImporter "TgaImporter")
+-   `--converter CONVERTER` -- image converter plugin (default: @ref Trade::TgaImageConverter "TgaImageConverter")
+-   `--plugin-dir DIR` -- base plugin dir (defaults to plugin directory in
+    %Magnum install location)
+-   `--output-size "X Y"` -- size of output image
+-   `--radius N` -- distance field computation radius
+
+The resulting image can be then used with @ref Shaders::DistanceFieldVector
+shader. See also @ref TextureTools::distanceField() for more information about
+the algorithm and parameters.
+
+@section magnum-distancefield-example Example usage
+
+    magnum-distancefieldconverter --importer PngImporter --output-size "256 256" --radius 24 logo.png logo.tga
+
+This will open binary `logo.png` image using @ref Trade::PngImporter "PngImporter"
+plugin and converts it to 256x256 distance field `logo.tga` using
+@ref Trade::TgaImageConverter "TgaImageConverter".
+
+*/
+
+namespace TextureTools {
 
 class DistanceFieldConverter: public Platform::WindowlessApplication {
     public: