Magnum::Text::DistanceFieldGlyphCacheGL class new in Git master
#include <Magnum/Text/DistanceFieldGlyphCacheGL.h>

OpenGL glyph cache with distance field rendering.

Unlike the base 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.

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 {128, 128} GlyphCacheGL was filled with a 12 pt font, a {1024, 1024} 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.

Containers::Pointer<Text::AbstractFont> font = …;
font->openFile("font.ttf", 96.0f);

Text::DistanceFieldGlyphCacheGL cache{Vector2i{1024}, Vector2i{128}, 12};
font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz"
                            "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
                            "0123456789?!:;,. ");

See the Renderer class for information about text rendering. The AbstractGlyphCache base class has more information about general glyph cache usage.

Internal texture format

The format() is always PixelFormat::R8Unorm.

On desktop OpenGL, OpenGL ES 3.0+, WebGL 2, and OpenGL ES 2.0 if EXT_texture_rg is supported, the processedFormat() is always PixelFormat::R8Unorm, which maps to GL::TextureFormat::R8 for the texture(), matching the behavior listed in GlyphCacheGL docs.

On OpenGL ES 2.0 without EXT_texture_rg and on WebGL 1, PixelFormat::R8Unorm maps to GL::TextureFormat::Luminance, which isn't renderable and thus cannot be used for calculating the distance field. Instead, PixelFormat::RGBA8Unorm is used for processedFormat(). This shouldn't affect common use through image(), but code interacting with processedImage() or setProcessedImage() may need to be aware of this.

Base classes

class GlyphCacheGL new in Git master: OpenGL glyph cache.

Constructors, destructors, conversion operators

DistanceFieldGlyphCacheGL(const Vector2i& size, const Vector2i& processedSize, UnsignedInt radius) explicit: Constructor.
DistanceFieldGlyphCacheGL(NoCreateT) explicit noexcept new in Git master: Construct without creating the internal state and the OpenGL texture object.

Public functions

auto distanceFieldTextureSize() const -> Vector2i deprecated in Git master: Distance field texture size.
void setDistanceFieldImage(const Vector2i& offset, const ImageView2D& image) deprecated in Git master: Set a distance field cache image.

Function documentation

Magnum::Text::DistanceFieldGlyphCacheGL::DistanceFieldGlyphCacheGL(const Vector2i& size, const Vector2i& processedSize, UnsignedInt radius) explicit

Constructor.

Parameters
size	Size of the source image
processedSize	Resulting distance field texture size
radius	Distance field computation radius

See TextureTools::DistanceField for more information about the parameters. Size restrictions from it apply here as well, in particular the ratio of size and processedSize is expected to be a multiple of 2.

Sets the processedFormat() to PixelFormat::R8Unorm, if available. On OpenGL ES 3.0+ and WebGL 2 uses always. On desktop OpenGL requires ARB_texture_rg (part of OpenGL 3.0), on ES2 uses EXT_texture_rg if available and uses PixelFormat::RGB8Unorm as fallback if not, on WebGL 1 uses PixelFormat::RGB8Unorm always.

Magnum::Text::DistanceFieldGlyphCacheGL::DistanceFieldGlyphCacheGL(NoCreateT) explicit noexcept new in Git master

Construct without creating the internal state and the OpenGL texture object.

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 NoCreate for alternatives.

Vector2i Magnum::Text::DistanceFieldGlyphCacheGL::distanceFieldTextureSize() const

Distance field texture size.

Compared to textureSize(), which is the size of the source image, this function returns size of the resulting distance field texture.

void Magnum::Text::DistanceFieldGlyphCacheGL::setDistanceFieldImage(const Vector2i& offset, const ImageView2D& image)

Set a distance field cache image.

Compared to setImage() uploads an already computed distance field image to given offset in the distance field texture. The offset and ImageView::size() are expected to be in bounds for distanceFieldTextureSize().