Magnum::Text::DistanceFieldGlyphCache class
#include <Magnum/Text/DistanceFieldGlyphCache.h>

Glyph cache with distance field rendering.

Unlike the base GlyphCache, this class converts each binary image to a distance field. It's not possible to use non-binary colors with this cache 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} GlyphCache 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::DistanceFieldGlyphCache 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.

Base classes

class GlyphCache: Glyph cache.

Constructors, destructors, conversion operators

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

Public functions

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

Function documentation

Magnum::Text::DistanceFieldGlyphCache::DistanceFieldGlyphCache(const Vector2i& sourceSize, const Vector2i& size, UnsignedInt radius) explicit

Constructor.

Parameters
sourceSize	Size of the source image
size	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 sourceSize and size is expected to be a multiple of 2.

Sets the internal texture format to single-channel. On OpenGL ES 3.0+ and WebGL 2 uses GL::TextureFormat::R8. On desktop OpenGL requires ARB_texture_rg (part of OpenGL 3.0), on ES2 uses EXT_texture_rg if available or GL::TextureFormat::RGB as fallback, on WebGL 1 uses GL::TextureFormat::RGB always.

Magnum::Text::DistanceFieldGlyphCache::DistanceFieldGlyphCache(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::DistanceFieldGlyphCache::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::DistanceFieldGlyphCache::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().