Magnum::Text::GlyphCache class

Glyph cache.

Contents

Contains font glyphs prerendered into texture atlas.

Usage

Create GlyphCache object with sufficient size and then call AbstractFont::createGlyphCache() to fill it with glyphs.

std::unique_ptr<Text::AbstractFont> font;
Text::GlyphCache cache{Vector2i{512}};
font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz"
                            "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
                            "0123456789?!:;,. ");

See Renderer for information about text rendering.

Derived classes

class DistanceFieldGlyphCache
Glyph cache with distance field rendering.

Constructors, destructors, conversion operators

GlyphCache(GL::TextureFormat internalFormat, const Vector2i& originalSize, const Vector2i& size, const Vector2i& padding) explicit
Constructor.
GlyphCache(GL::TextureFormat internalFormat, const Vector2i& size, const Vector2i& padding = {}) explicit
Constructor.
GlyphCache(const Vector2i& originalSize, const Vector2i& size, const Vector2i& padding) explicit
Constructor.
GlyphCache(const Vector2i& size, const Vector2i& padding = {}) explicit
Constructor.

Public functions

auto textureSize() const -> Vector2i
Cache size.
auto padding() const -> Vector2i
Glyph padding.
auto glyphCount() const -> std::size_t
Count of glyphs in the cache.
auto texture() -> GL::Texture2D&
Cache texture.
auto operator[](UnsignedInt glyph) const -> std::pair<Vector2i, Range2Di>
Parameters of given glyph.
auto begin() const -> std::unordered_map<UnsignedInt, std::pair<Vector2i, Range2Di>>::const_iterator
Iterator access to cache data.
auto end() const -> std::unordered_map<UnsignedInt, std::pair<Vector2i, Range2Di>>::const_iterator
Iterator access to cache data.
auto reserve(const std::vector<Vector2i>& sizes) -> std::vector<Range2Di>
Layout glyphs with given sizes to the cache.
void insert(UnsignedInt glyph, const Vector2i& position, const Range2Di& rectangle)
Insert glyph to cache.
void setImage(const Vector2i& offset, const ImageView2D& image) virtual
Set cache image.

Function documentation

Magnum::Text::GlyphCache::GlyphCache(GL::TextureFormat internalFormat, const Vector2i& originalSize, const Vector2i& size, const Vector2i& padding) explicit

Constructor.

Parameters
internalFormat Internal texture format
originalSize Unscaled glyph cache texture size
size Actual glyph cache texture size
padding Padding around every glyph

All glyphs parameters are saved relative to originalSize, although the actual glyph cache texture has size. Glyph padding can be used to account for e.g. glyph shadows.

Magnum::Text::GlyphCache::GlyphCache(GL::TextureFormat internalFormat, const Vector2i& size, const Vector2i& padding = {}) explicit

Constructor.

Same as calling the above with originalSize and size the same.

Magnum::Text::GlyphCache::GlyphCache(const Vector2i& originalSize, const Vector2i& size, const Vector2i& padding) explicit

Constructor.

Sets internal texture format to red channel only. On desktop OpenGL requires ARB_texture_rg (also part of OpenGL ES 3.0 and WebGL 2), on ES2 unconditionally uses GL::TextureFormat::Luminance. This is done for consistency with GL::pixelFormat(), which unconditionally returns GL::PixelFormat::Luminance for PixelFormat::R8Unorm. See GlyphCache(GL::TextureFormat, const Vector2i&, const Vector2i&) for an alternative.

Magnum::Text::GlyphCache::GlyphCache(const Vector2i& size, const Vector2i& padding = {}) explicit

Constructor.

Same as calling the above with originalSize and size the same.

Vector2i Magnum::Text::GlyphCache::textureSize() const

Cache size.

Size of unscaled glyph cache texture.

std::pair<Vector2i, Range2Di> Magnum::Text::GlyphCache::operator[](UnsignedInt glyph) const

Parameters of given glyph.

Parameters
glyph Glyph ID

First tuple element is glyph position relative to point on baseline, second element is glyph region in texture atlas.

Returned values include padding.

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 to some meaningful value in insert().

std::vector<Range2Di> Magnum::Text::GlyphCache::reserve(const std::vector<Vector2i>& sizes)

Layout glyphs with given sizes to the cache.

Returns non-overlapping regions in cache texture to store glyphs. The reserved space is reused on next call to reserve() if no glyph was stored there, use insert() to store actual glyph on given position and setImage() to upload glyph image.

Glyph sizes are expected to be without padding.

void Magnum::Text::GlyphCache::insert(UnsignedInt glyph, const Vector2i& position, const Range2Di& rectangle)

Insert glyph to cache.

Parameters
glyph Glyph ID
position Position relative to point on baseline
rectangle Region in texture atlas

You can obtain unused non-overlapping regions with reserve(). You can't overwrite already inserted glyph, however you can reset glyph 0 to some meaningful value.

Glyph parameters are expected to be without padding.

See also setImage() to upload glyph image.

void Magnum::Text::GlyphCache::setImage(const Vector2i& offset, const ImageView2D& image) virtual

Set cache image.

Uploads image for one or more glyphs to given offset in cache texture.