diff --git a/doc/utilities.dox b/doc/utilities.dox new file mode 100644 index 000000000..dd6cff029 --- /dev/null +++ b/doc/utilities.dox @@ -0,0 +1,35 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014 + 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 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 + +*/ +} diff --git a/src/Magnum/Platform/magnum-info.cpp b/src/Magnum/Platform/magnum-info.cpp index bc24d5ebe..bc7b0b7ef 100644 --- a/src/Magnum/Platform/magnum-info.cpp +++ b/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); diff --git a/src/Magnum/Text/AbstractFontConverter.h b/src/Magnum/Text/AbstractFontConverter.h index 7df3c89e4..015ce5038 100644 --- a/src/Magnum/Text/AbstractFontConverter.h +++ b/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*()` / diff --git a/src/Magnum/Text/fontconverter.cpp b/src/Magnum/Text/fontconverter.cpp index 79db061fd..ab890dcb7 100644 --- a/src/Magnum/Text/fontconverter.cpp +++ b/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) diff --git a/src/Magnum/TextureTools/DistanceField.h b/src/Magnum/TextureTools/DistanceField.h index 5924d40bc..342ecb092 100644 --- a/src/Magnum/TextureTools/DistanceField.h +++ b/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 diff --git a/src/Magnum/TextureTools/distancefieldconverter.cpp b/src/Magnum/TextureTools/distancefieldconverter.cpp index 1c7d362fd..703e2ed3d 100644 --- a/src/Magnum/TextureTools/distancefieldconverter.cpp +++ b/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: