mirror of https://github.com/mosra/magnum.git
Browse Source
Like with TextureTools::DistanceField, to make room for non-GL implementations. Old names are deprecated aliases, same for headers. The only remaining bit in the Text library is the Renderer class, but for that one I first need to invent a non-shitty API so I can just deprecate the old thing as a whole and create something reasonable from scratch in RendererGL.pull/650/head
Vladimír Vondruš
2 years ago
20 changed files with 555 additions and 421 deletions
@ -0,0 +1,180 @@
|
||||
#ifndef Magnum_Text_DistanceFieldGlyphCacheGL_h |
||||
#define Magnum_Text_DistanceFieldGlyphCacheGL_h |
||||
/*
|
||||
This file is part of Magnum. |
||||
|
||||
Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, |
||||
2020, 2021, 2022, 2023 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. |
||||
*/ |
||||
|
||||
/** @file
|
||||
* @brief Class @ref Magnum::Text::DistanceFieldGlyphCacheGL |
||||
* @m_since_latest |
||||
*/ |
||||
|
||||
#include "Magnum/configure.h" |
||||
|
||||
#ifdef MAGNUM_TARGET_GL |
||||
#include "Magnum/Text/GlyphCacheGL.h" |
||||
#include "Magnum/TextureTools/DistanceFieldGL.h" |
||||
|
||||
namespace Magnum { namespace Text { |
||||
|
||||
/**
|
||||
@brief OpenGL glyph cache with distance field rendering |
||||
@m_since_latest |
||||
|
||||
Unlike the base @ref GlyphCacheGL, this class converts each binary image to a |
||||
distance field. It's not possible to only use this cache for monochrome glyphs |
||||
as the internal texture format is single-channel. |
||||
|
||||
@section Text-DistanceFieldGlyphCacheGL-usage Usage |
||||
|
||||
In order to create a distance field glyph cache, the font has to be loaded at a |
||||
size significantly larger than what the resulting text will be. The distance |
||||
field conversion process then converts the input to a fraction of its size |
||||
again, transferring the the extra spatial resolution to distance values. The |
||||
distance values are then used to render an arbitrarily sized text without it |
||||
being jaggy at small sizes and blurry when large. |
||||
|
||||
The process requires three input parameters, size of the source image, size of |
||||
the resulting glyph cache image and a radius for the distance field creation. |
||||
The ratio between the input and output image size is usually four or eight |
||||
times, and the size of the font should match the larger size. So, for example, |
||||
if a @cpp {128, 128} @ce @ref GlyphCacheGL was filled with a 12 pt font, a |
||||
@cpp {1024, 1024} @ce source image for the distance field should use a 96 pt |
||||
font. The radius should then be chosen so it's at least one or two pixels in |
||||
the scaled-down result, so in this case at least 8. Values less than that will |
||||
result in aliasing artifacts. Very high radius values are needed only if |
||||
outlining, thinning, thickening or shadow effects will be used when rendering, |
||||
using them leads to precision loss when the distance field is stored in 8-bit |
||||
channels. |
||||
|
||||
@snippet Text-gl.cpp DistanceFieldGlyphCacheGL-usage |
||||
|
||||
See the @ref Renderer class for information about text rendering. The |
||||
@ref AbstractGlyphCache base class has more information about general glyph |
||||
cache usage. |
||||
|
||||
@section Text-DistanceFieldGlyphCacheGL-internal-format Internal texture format |
||||
|
||||
The @ref format() is always @ref PixelFormat::R8Unorm. |
||||
|
||||
On desktop OpenGL, OpenGL ES 3.0+, WebGL 2, and OpenGL ES 2.0 if |
||||
@gl_extension{EXT,texture_rg} is supported, the @ref processedFormat() is |
||||
always @ref PixelFormat::R8Unorm, which maps to @ref GL::TextureFormat::R8 for |
||||
the @ref texture(), matching |
||||
@ref Text-GlyphCacheGL-internal-format "the behavior listed in GlyphCacheGL docs". |
||||
|
||||
On OpenGL ES 2.0 without @gl_extension{EXT,texture_rg} and on WebGL 1, |
||||
@ref PixelFormat::R8Unorm maps to @ref GL::TextureFormat::Luminance, which |
||||
isn't renderable and thus cannot be used for calculating the distance field. |
||||
Instead, @ref PixelFormat::RGBA8Unorm is used for @ref processedFormat(). This |
||||
shouldn't affect common use through @ref image(), but code interacting with |
||||
@ref processedImage() or @ref setProcessedImage() may need to be aware of this. |
||||
|
||||
@note This class is available only if Magnum is compiled with |
||||
@ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features |
||||
for more information. |
||||
|
||||
@see @ref TextureTools::DistanceFieldGL |
||||
*/ |
||||
class MAGNUM_TEXT_EXPORT DistanceFieldGlyphCacheGL: public GlyphCacheGL { |
||||
public: |
||||
/**
|
||||
* @brief Constructor |
||||
* @param size Size of the source image |
||||
* @param processedSize Resulting distance field texture size |
||||
* @param radius Distance field computation radius |
||||
* |
||||
* See @ref TextureTools::DistanceField for more information about the |
||||
* parameters. Size restrictions from it apply here as well, in |
||||
* particular the ratio of @p size and @p processedSize is expected to |
||||
* be a multiple of 2. |
||||
* |
||||
* Sets the @ref processedFormat() to @ref PixelFormat::R8Unorm, if |
||||
* available. On OpenGL ES 3.0+ and WebGL 2 uses always. On desktop |
||||
* OpenGL requires @gl_extension{ARB,texture_rg} (part of OpenGL 3.0), |
||||
* on ES2 uses @gl_extension{EXT,texture_rg} if available and uses |
||||
* @ref PixelFormat::RGB8Unorm as fallback if not, on WebGL 1 uses |
||||
* @ref PixelFormat::RGB8Unorm always. |
||||
*/ |
||||
explicit DistanceFieldGlyphCacheGL(const Vector2i& size, const Vector2i& processedSize, UnsignedInt radius); |
||||
|
||||
/**
|
||||
* @brief Construct without creating the internal state and the OpenGL texture object |
||||
* @m_since_latest |
||||
* |
||||
* The constructed instance is equivalent to moved-from state, i.e. no |
||||
* APIs can be safely called on the object. Useful in cases where you |
||||
* will overwrite the instance later anyway. Move another object over |
||||
* it to make it useful. |
||||
* |
||||
* This function can be safely used for constructing (and later |
||||
* destructing) objects even without any OpenGL context being active. |
||||
* However note that this is a low-level and a potentially dangerous |
||||
* API, see the documentation of @ref NoCreate for alternatives. |
||||
*/ |
||||
explicit DistanceFieldGlyphCacheGL(NoCreateT) noexcept; |
||||
|
||||
#ifdef MAGNUM_BUILD_DEPRECATED |
||||
/**
|
||||
* @brief Distance field texture size |
||||
* |
||||
* Compared to @ref textureSize(), which is the size of the source |
||||
* image, this function returns size of the resulting distance field |
||||
* texture. |
||||
* @m_deprecated_since_latest Use @ref processedSize() instead. |
||||
*/ |
||||
CORRADE_DEPRECATED("use processedSize() instead") Vector2i distanceFieldTextureSize() const { |
||||
return processedSize().xy(); |
||||
} |
||||
|
||||
/**
|
||||
* @brief Set a distance field cache image |
||||
* |
||||
* Compared to @ref setImage() uploads an already computed distance |
||||
* field image to given offset in the distance field texture. The |
||||
* @p offset and @ref ImageView::size() are expected to be in bounds |
||||
* for @ref distanceFieldTextureSize(). |
||||
* @m_deprecated_since_latest Use @ref setProcessedImage() instead. |
||||
*/ |
||||
CORRADE_DEPRECATED("use setProcessedImage() instead") void setDistanceFieldImage(const Vector2i& offset, const ImageView2D& image); |
||||
#endif |
||||
|
||||
private: |
||||
MAGNUM_TEXT_LOCAL GlyphCacheFeatures doFeatures() const override; |
||||
MAGNUM_TEXT_LOCAL void doSetImage(const Vector2i& offset, const ImageView2D& image) override; |
||||
MAGNUM_TEXT_LOCAL void doSetProcessedImage(const Vector2i& offset, const ImageView2D& image) override; |
||||
|
||||
#ifndef MAGNUM_TARGET_GLES |
||||
MAGNUM_TEXT_LOCAL Image3D doProcessedImage() override; |
||||
#endif |
||||
|
||||
TextureTools::DistanceFieldGL _distanceField; |
||||
}; |
||||
|
||||
}} |
||||
#else |
||||
#error this header is available only in the OpenGL build |
||||
#endif |
||||
|
||||
#endif |
||||
@ -0,0 +1,198 @@
|
||||
#ifndef Magnum_Text_GlyphCacheGL_h |
||||
#define Magnum_Text_GlyphCacheGL_h |
||||
/*
|
||||
This file is part of Magnum. |
||||
|
||||
Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, |
||||
2020, 2021, 2022, 2023 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. |
||||
*/ |
||||
|
||||
/** @file
|
||||
* @brief Class @ref Magnum::Text::GlyphCacheGL |
||||
* @m_since_latest |
||||
*/ |
||||
|
||||
#include "Magnum/configure.h" |
||||
|
||||
#ifdef MAGNUM_TARGET_GL |
||||
#include "Magnum/GL/Texture.h" |
||||
#include "Magnum/Text/AbstractGlyphCache.h" |
||||
|
||||
namespace Magnum { namespace Text { |
||||
|
||||
/**
|
||||
@brief OpenGL glyph cache |
||||
@m_since_latest |
||||
|
||||
Contains font glyphs rendered into a texture atlas. |
||||
|
||||
@section Text-GlyphCacheGL-usage Usage |
||||
|
||||
Create the @ref GlyphCacheGL object with sufficient size and then call |
||||
@ref AbstractFont::createGlyphCache() to fill it with glyphs. |
||||
|
||||
@snippet Text-gl.cpp GlyphCacheGL-usage |
||||
|
||||
See the @ref Renderer class for information about text rendering. The |
||||
@ref AbstractGlyphCache base class has more information about general glyph |
||||
cache usage. |
||||
|
||||
@section Text-GlyphCacheGL-internal-format Internal texture format |
||||
|
||||
The @ref GL::TextureFormat used by @ref texture() is implicitly coming from |
||||
@ref GL::textureFormat(Magnum::PixelFormat) applied to @ref format(), or if |
||||
@ref GlyphCacheFeature::ImageProcessing is supported, to @ref processedFormat() |
||||
instead. |
||||
|
||||
If @ref PixelFormat::R8Unorm is used for @ref format() or if |
||||
@ref GlyphCacheFeature::ImageProcessing is supported and |
||||
@ref PixelFormat::R8Unorm is used for @ref processedFormat(), on desktop OpenGL |
||||
the class expects that @gl_extension{ARB,texture_rg} (OpenGL 3.0) is supported |
||||
and uses @ref GL::TextureFormat::R8. On OpenGL ES 2.0, if |
||||
@gl_extension{EXT,texture_rg} is supported, @ref GL::TextureFormat::Red / |
||||
@ref GL::TextureFormat::R8 is used instead of @ref GL::TextureFormat::Luminance |
||||
for @ref PixelFormat::R8Unorm. On WebGL 1 @ref GL::TextureFormat::Luminance is |
||||
used for @ref PixelFormat::R8Unorm always. |
||||
|
||||
While this is abstracted away to not affect common use through @ref image(), |
||||
@ref processedImage() or @ref setProcessedImage(), code interacting directly |
||||
with @ref texture() may need to special-case this. In particular, if image |
||||
processing needs to render to the texture, it may need to choose a different |
||||
format as luminance usually cannot be rendered to. |
||||
|
||||
@todo Default glyph 0 with rect 0 0 0 0 will result in negative dimensions when |
||||
nonzero padding is removed |
||||
|
||||
@note This class is available only if Magnum is compiled with |
||||
@ref MAGNUM_TARGET_GL enabled (done by default). See @ref building-features |
||||
for more information. |
||||
*/ |
||||
class MAGNUM_TEXT_EXPORT GlyphCacheGL: public AbstractGlyphCache { |
||||
public: |
||||
/**
|
||||
* @brief Constructor |
||||
* @param format Source image format |
||||
* @param size Source image size size in pixels |
||||
* @param padding Padding around every glyph in pixels |
||||
* @m_since_latest |
||||
* |
||||
* The @p size is expected to be non-zero. If the implementation |
||||
* advertises @ref GlyphCacheFeature::ImageProcessing, the |
||||
* @ref processedFormat() and @ref processedSize() is the same as |
||||
* @p format and @p size, use @ref AbstractGlyphCache(PixelFormat, const Vector3i&, PixelFormat, const Vector2i&, const Vector2i&) |
||||
* to specify different values. |
||||
*/ |
||||
explicit GlyphCacheGL(PixelFormat format, const Vector2i& size, const Vector2i& padding = Vector2i{1}); |
||||
|
||||
/**
|
||||
* @brief Construct with a specific processed format and size |
||||
* @param format Source image format |
||||
* @param size Source image size size in pixels |
||||
* @param processedFormat Processed image format |
||||
* @param processedSize Processed glyph cache texture size in |
||||
* pixels |
||||
* @param padding Padding around every glyph in pixels. See |
||||
* @ref Text-AbstractGlyphCache-padding for more information about |
||||
* the default. |
||||
* @m_since_latest |
||||
* |
||||
* The @p size and @p processedSize is expected to be non-zero. All |
||||
* glyphs are saved in @p format relative to @p size and with |
||||
* @p padding, although the actual glyph cache texture is in |
||||
* @p processedFormat and has @p processedSize. |
||||
* @see @ref AbstractGlyphCache(PixelFormat, const Vector2i&, const Vector2i&) |
||||
*/ |
||||
explicit GlyphCacheGL(PixelFormat format, const Vector2i& size, PixelFormat processedFormat, const Vector2i& processedSize, const Vector2i& padding = Vector2i{1}); |
||||
|
||||
#ifdef MAGNUM_BUILD_DEPRECATED |
||||
/**
|
||||
* @brief Constructor |
||||
* @m_deprecated_since_latest Use @ref GlyphCacheGL(PixelFormat, const Vector2i&, const Vector2i&) |
||||
* instead. |
||||
*/ |
||||
CORRADE_DEPRECATED("use GlyphCacheGL(PixelFormat, const Vector2i&, const Vector2i&, const Vector2i&) instead") explicit GlyphCacheGL(GL::TextureFormat internalFormat, const Vector2i& size, const Vector2i& padding = Vector2i{1}); |
||||
|
||||
/**
|
||||
* @brief Construct with a specific processed size |
||||
* @m_deprecated_since_latest Use @ref GlyphCacheGL(PixelFormat, const Vector2i&, PixelFormat, const Vector2i&, const Vector2i&) |
||||
* instead. |
||||
*/ |
||||
CORRADE_DEPRECATED("use GlyphCacheGL(PixelFormat, const Vector2i&, const Vector2i&, const Vector2i&) instead") explicit GlyphCacheGL(GL::TextureFormat internalFormat, const Vector2i& size, const Vector2i& processedSize, const Vector2i& padding); |
||||
|
||||
/**
|
||||
* @brief Construct with an implicit format |
||||
* |
||||
* Calls @ref GlyphCacheGL(PixelFormat, const Vector2i&, const Vector2i&) |
||||
* with @p format set to @ref PixelFormat::R8Unorm. |
||||
* @m_deprecated_since_latest Use @ref GlyphCacheGL(PixelFormat, const Vector2i&, const Vector2i&) |
||||
* and explicitly pass the format instead. |
||||
*/ |
||||
CORRADE_DEPRECATED("use GlyphCacheGL(PixelFormat, const Vector2i&, const Vector2i&, const Vector2i&) instead") explicit GlyphCacheGL(const Vector2i& size, const Vector2i& padding = Vector2i{1}); |
||||
|
||||
/**
|
||||
* @brief Construct with an implicit format and a specific processed size |
||||
* |
||||
* Calls @ref GlyphCacheGL(PixelFormat, const Vector2i&, PixelFormat, const Vector2i&, const Vector2i&) |
||||
* with @p format and @p processedFormat set to |
||||
* @ref PixelFormat::R8Unorm. |
||||
* @m_deprecated_since_latest Use @ref GlyphCacheGL(PixelFormat, const Vector2i&, PixelFormat, const Vector2i&, const Vector2i&) |
||||
* and explicitly pass the format instead. |
||||
*/ |
||||
CORRADE_DEPRECATED("use GlyphCacheGL(PixelFormat, const Vector2i&, const Vector2i&, const Vector2i&) instead") explicit GlyphCacheGL(const Vector2i& size, const Vector2i& processedSize, const Vector2i& padding); |
||||
#endif |
||||
|
||||
/**
|
||||
* @brief Construct without creating the internal state and the OpenGL texture object |
||||
* @m_since_latest |
||||
* |
||||
* The constructed instance is equivalent to moved-from state, i.e. no |
||||
* APIs can be safely called on the object. Useful in cases where you |
||||
* will overwrite the instance later anyway. Move another object over |
||||
* it to make it useful. |
||||
* |
||||
* This function can be safely used for constructing (and later |
||||
* destructing) objects even without any OpenGL context being active. |
||||
* However note that this is a low-level and a potentially dangerous |
||||
* API, see the documentation of @ref NoCreate for alternatives. |
||||
*/ |
||||
explicit GlyphCacheGL(NoCreateT) noexcept; |
||||
|
||||
/** @brief Cache texture */ |
||||
GL::Texture2D& texture() { return _texture; } |
||||
|
||||
#ifdef DOXYGEN_GENERATING_OUTPUT |
||||
private: |
||||
#else |
||||
protected: |
||||
#endif |
||||
GL::Texture2D _texture; |
||||
|
||||
private: |
||||
MAGNUM_TEXT_LOCAL GlyphCacheFeatures doFeatures() const override; |
||||
MAGNUM_TEXT_LOCAL void doSetImage(const Vector2i& offset, const ImageView2D& image) override; |
||||
}; |
||||
|
||||
}} |
||||
#else |
||||
#error this header is available only in the OpenGL build |
||||
#endif |
||||
|
||||
#endif |
||||
Loading…
Reference in new issue