ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Text: doc++

pull/34/head
Vladimír Vondruš 13 years ago
parent
f92e21e5c7
commit
446b48bbb7
5 changed files with 57 additions and 54 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 47
      src/Text/AbstractFont.h
  2. 16
      src/Text/AbstractFontConverter.h
  3. 16
      src/Text/DistanceFieldGlyphCache.h
  4. 24
      src/Text/GlyphCache.h
  5. 8
      src/Text/Renderer.h

47
src/Text/AbstractFont.h
Unescape View File

@ -25,7 +25,7 @@
*/ */
/** @file /** @file
* @brief Class Magnum::Text::AbstractFont, Magnum::Text::AbstractLayouter * @brief Class @ref Magnum::Text::AbstractFont, @ref Magnum::Text::AbstractLayouter
*/ */
#include <memory> #include <memory>
@ -45,9 +45,10 @@ namespace Magnum { namespace Text {
@section AbstractFont-usage Usage @section AbstractFont-usage Usage
First step is to open the font using @ref open(), next step is to prerender all First step is to open the font using @ref openData(), @ref openSingleData() or
the glyphs which will be used in text rendering later, see @ref GlyphCache for @ref openFile(). Next step is to prerender all the glyphs which will be used in
more information. See @ref Renderer for information about text rendering. text rendering later, see @ref GlyphCache for more information. See
@ref Renderer for information about text rendering.
@section AbstractFont-subclassing Subclassing @section AbstractFont-subclassing Subclassing
@ -72,14 +73,14 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin {
/** /**
* @brief Features supported by this importer * @brief Features supported by this importer
* *
* @see Features, features() * @see @ref Features, @ref features()
*/ */
enum class Feature: UnsignedByte { enum class Feature: UnsignedByte {
/** Opening fonts from raw data using openData() */ /** Opening fonts from raw data using @ref openData() */
OpenData = 1 << 0, OpenData = 1 << 0,
/** /**
* The format is multi-file, thus openSingleData() convenience * The format is multi-file, thus @ref openSingleData() convenience
* function cannot be used. * function cannot be used.
*/ */
MultiFile = 1 << 1, MultiFile = 1 << 1,
@ -87,7 +88,7 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin {
/** /**
* The font contains prepared glyph cache. * The font contains prepared glyph cache.
* *
* @see fillGlyphCache(), createGlyphCache() * @see @ref fillGlyphCache(), @ref createGlyphCache()
*/ */
PreparedGlyphCache = 1 << 2 PreparedGlyphCache = 1 << 2
}; };
@ -163,7 +164,7 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin {
* *
* @note This function is not meant to be used in performance-critical * @note This function is not meant to be used in performance-critical
* code, only for font observations and conversions. * code, only for font observations and conversions.
* @see glyphId() * @see @ref glyphId()
*/ */
Vector2 glyphAdvance(UnsignedInt glyph); Vector2 glyphAdvance(UnsignedInt glyph);
@ -194,7 +195,7 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin {
* @param size Font size * @param size Font size
* @param text %Text to layout * @param text %Text to layout
* *
* @see fillGlyphCache(), createGlyphCache() * @see @ref fillGlyphCache(), @ref createGlyphCache()
*/ */
std::unique_ptr<AbstractLayouter> layout(const GlyphCache& cache, Float size, const std::string& text); std::unique_ptr<AbstractLayouter> layout(const GlyphCache& cache, Float size, const std::string& text);
@ -210,25 +211,25 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin {
#else #else
private: private:
#endif #endif
/** @brief Implementation for features() */ /** @brief Implementation for @ref features() */
virtual Features doFeatures() const = 0; virtual Features doFeatures() const = 0;
/** @brief Implementation for isOpened() */ /** @brief Implementation for @ref isOpened() */
virtual bool doIsOpened() const = 0; virtual bool doIsOpened() const = 0;
/** /**
* @brief Implementation for openData() * @brief Implementation for @ref openData()
* *
* If the plugin doesn't have @ref Feature::MultiFile, default * If the plugin doesn't have @ref Feature::MultiFile, default
* implementation calls @ref doOpenSingleData(). * implementation calls @ref doOpenSingleData().
*/ */
virtual void doOpenData(const std::vector<std::pair<std::string, Containers::ArrayReference<const unsigned char>>>& data, Float size); virtual void doOpenData(const std::vector<std::pair<std::string, Containers::ArrayReference<const unsigned char>>>& data, Float size);
/** @brief Implementation for openSingleData() */ /** @brief Implementation for @ref openSingleData() */
virtual void doOpenSingleData(Containers::ArrayReference<const unsigned char> data, Float size); virtual void doOpenSingleData(Containers::ArrayReference<const unsigned char> data, Float size);
/** /**
* @brief Implementation for openFile() * @brief Implementation for @ref openFile()
* *
* If @ref Feature::OpenData is supported and the plugin doesn't have * If @ref Feature::OpenData is supported and the plugin doesn't have
* @ref Feature::MultiFile, default implementation opens the file and * @ref Feature::MultiFile, default implementation opens the file and
@ -236,17 +237,17 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin {
*/ */
virtual void doOpenFile(const std::string& filename, Float size); virtual void doOpenFile(const std::string& filename, Float size);
/** @brief Implementation for close() */ /** @brief Implementation for @ref close() */
virtual void doClose() = 0; virtual void doClose() = 0;
/** @brief Implementation for glyphId() */ /** @brief Implementation for @ref glyphId() */
virtual UnsignedInt doGlyphId(char32_t character) = 0; virtual UnsignedInt doGlyphId(char32_t character) = 0;
/** @brief Implementation for glyphAdvance() */ /** @brief Implementation for @ref glyphAdvance() */
virtual Vector2 doGlyphAdvance(UnsignedInt glyph) = 0; virtual Vector2 doGlyphAdvance(UnsignedInt glyph) = 0;
/** /**
* @brief Implementation for createGlyphCache() * @brief Implementation for @ref fillGlyphCache()
* *
* The string is converted from UTF-8 to UTF-32, unique characters are * The string is converted from UTF-8 to UTF-32, unique characters are
* *not* removed. * *not* removed.
@ -260,12 +261,10 @@ class MAGNUM_TEXT_EXPORT AbstractFont: public PluginManager::AbstractPlugin {
virtual void doFillGlyphCache(GlyphCache& cache, const std::vector<char32_t>& characters); virtual void doFillGlyphCache(GlyphCache& cache, const std::vector<char32_t>& characters);
#endif #endif
/** /** @brief Implementation for @ref createGlyphCache() */
* @brief Implementation for createGlyphCache()
*/
virtual std::unique_ptr<GlyphCache> doCreateGlyphCache(); virtual std::unique_ptr<GlyphCache> doCreateGlyphCache();
/** @brief Implementation for layout() */ /** @brief Implementation for @ref layout() */
virtual std::unique_ptr<AbstractLayouter> doLayout(const GlyphCache& cache, Float size, const std::string& text) = 0; virtual std::unique_ptr<AbstractLayouter> doLayout(const GlyphCache& cache, Float size, const std::string& text) = 0;
}; };
@ -274,7 +273,7 @@ CORRADE_ENUMSET_OPERATORS(AbstractFont::Features)
/** /**
@brief Base for text layouters @brief Base for text layouters
Returned by AbstractFont::layout(). Returned by @ref AbstractFont::layout().
*/ */
class MAGNUM_TEXT_EXPORT AbstractLayouter { class MAGNUM_TEXT_EXPORT AbstractLayouter {
AbstractLayouter(const AbstractLayouter&) = delete; AbstractLayouter(const AbstractLayouter&) = delete;

16
src/Text/AbstractFontConverter.h
Unescape View File

@ -25,7 +25,7 @@
*/ */
/** @file /** @file
* @brief Class Magnum::Text::AbstractFontConverter * @brief Class @ref Magnum::Text::AbstractFontConverter
*/ */
#include <memory> #include <memory>
@ -44,9 +44,10 @@ Provides functionality for converting arbitrary font to different format.
@section AbstractFontConverter-subclassing Subclassing @section AbstractFontConverter-subclassing Subclassing
Plugin implements doFeatures() and one or more of `exportTo*()` / `importFrom*()` Plugin implements @ref doFeatures() and one or more of `exportTo*()` /
functions based on what features are supported. Characters passed to font `importFrom*()` functions based on what features are supported. Characters
exporting functions are converted to list of unique UTF-32 characters. passed to font exporting functions are converted to list of unique UTF-32
characters.
You don't need to do most of the redundant sanity checks, these things are You don't need to do most of the redundant sanity checks, these things are
checked by the implementation: checked by the implementation:
@ -290,7 +291,8 @@ class MAGNUM_TEXT_EXPORT AbstractFontConverter: public PluginManager::AbstractPl
* @brief Implementation for @ref exportFontToFile() * @brief Implementation for @ref exportFontToFile()
* *
* If @ref Feature::ConvertData is supported, default implementation * If @ref Feature::ConvertData is supported, default implementation
* calls doExportFontToData() and saves the result to given file(s). * calls @ref doExportFontToData() and saves the result to given
* file(s).
* @note On Windows uses `std::vector<char32_t>` instead of * @note On Windows uses `std::vector<char32_t>` instead of
* `std::u32string`. See @ref Corrade::Utility::Unicode::utf32() * `std::u32string`. See @ref Corrade::Utility::Unicode::utf32()
* for more information. * for more information.
@ -309,7 +311,7 @@ class MAGNUM_TEXT_EXPORT AbstractFontConverter: public PluginManager::AbstractPl
*/ */
virtual std::vector<std::pair<std::string, Containers::Array<unsigned char>>> doExportGlyphCacheToData(GlyphCache& cache, const std::string& filename) const; virtual std::vector<std::pair<std::string, Containers::Array<unsigned char>>> doExportGlyphCacheToData(GlyphCache& cache, const std::string& filename) const;
/** @brief Implementation for exportGlyphCacheToSingleData() */ /** @brief Implementation for @ref exportGlyphCacheToSingleData() */
virtual Containers::Array<unsigned char> doExportGlyphCacheToSingleData(GlyphCache& cache) const; virtual Containers::Array<unsigned char> doExportGlyphCacheToSingleData(GlyphCache& cache) const;
/** /**
@ -329,7 +331,7 @@ class MAGNUM_TEXT_EXPORT AbstractFontConverter: public PluginManager::AbstractPl
*/ */
virtual std::unique_ptr<GlyphCache> doImportGlyphCacheFromData(const std::vector<std::pair<std::string, Containers::ArrayReference<const unsigned char>>>& data) const; virtual std::unique_ptr<GlyphCache> doImportGlyphCacheFromData(const std::vector<std::pair<std::string, Containers::ArrayReference<const unsigned char>>>& data) const;
/** @brief Implementation for importGlyphCacheFromSingleData() */ /** @brief Implementation for @ref importGlyphCacheFromSingleData() */
virtual std::unique_ptr<GlyphCache> doImportGlyphCacheFromSingleData(Containers::ArrayReference<const unsigned char> data) const; virtual std::unique_ptr<GlyphCache> doImportGlyphCacheFromSingleData(Containers::ArrayReference<const unsigned char> data) const;
/** /**

16
src/Text/DistanceFieldGlyphCache.h
Unescape View File

@ -25,7 +25,7 @@
*/ */
/** @file /** @file
* @brief Class Magnum::Text::DistanceFieldGlyphCache * @brief Class @ref Magnum::Text::DistanceFieldGlyphCache
*/ */
#include "Text/GlyphCache.h" #include "Text/GlyphCache.h"
@ -35,13 +35,13 @@ namespace Magnum { namespace Text {
/** /**
@brief Glyph cache with distance field rendering @brief Glyph cache with distance field rendering
Unlike original GlyphCache converts each binary image to distance field. It is Unlike original @ref GlyphCache converts each binary image to distance field.
not possible to use non-binary colors with this cache, internal texture format It is not possible to use non-binary colors with this cache, internal texture
is red channel only. format is red channel only.
@section GlyphCache-usage Usage @section GlyphCache-usage Usage
Usage is similar to GlyphCache, additionally you need to specify size of Usage is similar to @ref GlyphCache, additionally you need to specify size of
resulting distance field texture. resulting distance field texture.
@code @code
Text::AbstractFont* font; Text::AbstractFont* font;
@ -51,7 +51,7 @@ font->createGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz"
"0123456789 "); "0123456789 ");
@endcode @endcode
@see TextureTools::distanceField() @see @ref TextureTools::distanceField()
*/ */
class MAGNUM_TEXT_EXPORT DistanceFieldGlyphCache: public GlyphCache { class MAGNUM_TEXT_EXPORT DistanceFieldGlyphCache: public GlyphCache {
public: public:
@ -61,8 +61,8 @@ class MAGNUM_TEXT_EXPORT DistanceFieldGlyphCache: public GlyphCache {
* @param size Actual glyph cache texture size * @param size Actual glyph cache texture size
* @param radius Distance field computation radius * @param radius Distance field computation radius
* *
* See TextureTools::distanceField() for more information about the * See @ref TextureTools::distanceField() for more information about
* parameters. Sets internal texture format to red channel only. On * the parameters. Sets internal texture format to red channel only. On
* desktop OpenGL requires @extension{ARB,texture_rg} (also part of * desktop OpenGL requires @extension{ARB,texture_rg} (also part of
* OpenGL ES 3.0), in ES2 uses @es_extension{EXT,texture_rg} if * OpenGL ES 3.0), in ES2 uses @es_extension{EXT,texture_rg} if
* available or @ref TextureFormat::RGB as fallback. * available or @ref TextureFormat::RGB as fallback.

24
src/Text/GlyphCache.h
Unescape View File

@ -25,7 +25,7 @@
*/ */
/** @file /** @file
* @brief Class Magnum::Text::GlyphCache * @brief Class @ref Magnum::Text::GlyphCache
*/ */
#include <vector> #include <vector>
@ -127,8 +127,8 @@ class MAGNUM_TEXT_EXPORT GlyphCache {
* *
* If no glyph is found, glyph `0` is returned, which is by default on * If no glyph is found, glyph `0` is returned, which is by default on
* zero position and has zero region in texture atlas. You can reset it * zero position and has zero region in texture atlas. You can reset it
* to some meaningful value in insert(). * to some meaningful value in @ref insert().
* @see padding() * @see @ref padding()
*/ */
std::pair<Vector2i, Rectanglei> operator[](UnsignedInt glyph) const { std::pair<Vector2i, Rectanglei> operator[](UnsignedInt glyph) const {
auto it = glyphs.find(glyph); auto it = glyphs.find(glyph);
@ -149,15 +149,15 @@ class MAGNUM_TEXT_EXPORT GlyphCache {
* @brief Layout glyphs with given sizes to the cache * @brief Layout glyphs with given sizes to the cache
* *
* Returns non-overlapping regions in cache texture to store glyphs. * Returns non-overlapping regions in cache texture to store glyphs.
* The reserved space is reused on next call to reserve() if no glyph * The reserved space is reused on next call to @ref reserve() if no
* was stored there, use insert() to store actual glyph on given * glyph was stored there, use @ref insert() to store actual glyph on
* position and setImage() to upload glyph image. * given position and @ref setImage() to upload glyph image.
* *
* Glyph @p sizes are expected to be without padding. * Glyph @p sizes are expected to be without padding.
* *
* @attention Cache size must be large enough to contain all rendered * @attention Cache size must be large enough to contain all rendered
* glyphs. * glyphs.
* @see padding() * @see @ref padding()
*/ */
std::vector<Rectanglei> reserve(const std::vector<Vector2i>& sizes); std::vector<Rectanglei> reserve(const std::vector<Vector2i>& sizes);
@ -167,14 +167,14 @@ class MAGNUM_TEXT_EXPORT GlyphCache {
* @param position Position relative to point on baseline * @param position Position relative to point on baseline
* @param rectangle Region in texture atlas * @param rectangle Region in texture atlas
* *
* You can obtain unused non-overlapping regions with reserve(). You * You can obtain unused non-overlapping regions with @ref reserve().
* can't overwrite already inserted glyph, however you can reset glyph * You can't overwrite already inserted glyph, however you can reset
* `0` to some meaningful value. * glyph `0` to some meaningful value.
* *
* Glyph parameters are expected to be without padding. * Glyph parameters are expected to be without padding.
* *
* See also setImage() to upload glyph image. * See also @ref setImage() to upload glyph image.
* @see padding() * @see @ref padding()
*/ */
void insert(UnsignedInt glyph, Vector2i position, Rectanglei rectangle); void insert(UnsignedInt glyph, Vector2i position, Rectanglei rectangle);

8
src/Text/Renderer.h
Unescape View File

@ -24,7 +24,7 @@
DEALINGS IN THE SOFTWARE. DEALINGS IN THE SOFTWARE.
*/ */
/** @file /** @file Text/Renderer.h
* @brief Class @ref Magnum::Text::AbstractRenderer, @ref Magnum::Text::Renderer, typedef @ref Magnum::Text::Renderer2D, @ref Magnum::Text::Renderer3D * @brief Class @ref Magnum::Text::AbstractRenderer, @ref Magnum::Text::Renderer, typedef @ref Magnum::Text::Renderer2D, @ref Magnum::Text::Renderer3D
*/ */
@ -197,8 +197,8 @@ shader.setTransformationProjectionMatrix(projection*Matrix3::translation(-rectan
glyphCache->texture()->bind(Shaders::VectorShader2D::FontTextureLayer); glyphCache->texture()->bind(Shaders::VectorShader2D::FontTextureLayer);
mesh.draw(); mesh.draw();
@endcode @endcode
See @ref render(AbstractFont&, const GlyphCache&, Float, const std::string&) and See @ref render(AbstractFont&, const GlyphCache&, Float, const std::string&, Alignment) and
@ref render(AbstractFont&, const GlyphCache&, Float, const std::string&, Buffer&, Buffer&, Buffer::Usage) @ref render(AbstractFont&, const GlyphCache&, Float, const std::string&, Buffer&, Buffer&, Buffer::Usage, Alignment)
for more information. for more information.
While this method is sufficient for one-shot rendering of static texts, for While this method is sufficient for one-shot rendering of static texts, for
@ -247,6 +247,7 @@ template<UnsignedInt dimensions> class MAGNUM_TEXT_EXPORT Renderer: public Abstr
* @param vertexBuffer %Buffer where to store vertices * @param vertexBuffer %Buffer where to store vertices
* @param indexBuffer %Buffer where to store indices * @param indexBuffer %Buffer where to store indices
* @param usage Usage of vertex and index buffer * @param usage Usage of vertex and index buffer
* @param alignment Text alignment
* *
* Returns mesh prepared for use with @ref Shaders::AbstractVector * Returns mesh prepared for use with @ref Shaders::AbstractVector
* subclasses and rectangle spanning the rendered text. * subclasses and rectangle spanning the rendered text.
@ -258,6 +259,7 @@ template<UnsignedInt dimensions> class MAGNUM_TEXT_EXPORT Renderer: public Abstr
* @param font Font * @param font Font
* @param cache Glyph cache * @param cache Glyph cache
* @param size Font size * @param size Font size
* @param alignment Text alignment
*/ */
explicit Renderer(AbstractFont& font, const GlyphCache& cache, Float size, Alignment alignment = Alignment::LineLeft); explicit Renderer(AbstractFont& font, const GlyphCache& cache, Float size, Alignment alignment = Alignment::LineLeft);
Renderer(AbstractFont&, GlyphCache&&, Float, Alignment alignment = Alignment::LineLeft) = delete; /**< @overload */ Renderer(AbstractFont&, GlyphCache&&, Float, Alignment alignment = Alignment::LineLeft) = delete; /**< @overload */

Write Preview
Loading…
Cancel
Save