Magnum::Text::AbstractGlyphCache class new in 2019.10

Base for glyph caches.

An API-agnostic base for glyph caches. See GlyphCache and DistanceFieldGlyphCache for concrete implementations.

Subclassing

The subclass needs to implement the doSetImage() function and manage the glyph cache image. The public setImage() function already does checking for rectangle bounds so it's not needed to do it again on the implementation side.

Derived classes

class GlyphCache
Glyph cache.

Constructors, destructors, conversion operators

AbstractGlyphCache(const Vector2i& size, const Vector2i& padding = {}) explicit
Constructor.

Public functions

auto features() const -> GlyphCacheFeatures
Features supported by this glyph cache implementation.
auto textureSize() const -> Vector2i
Glyph cache texture size.
auto padding() const -> Vector2i
Glyph padding.
auto glyphCount() const -> std::size_t
Count of glyphs in the cache.
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 a glyph to the cache.
void setImage(const Vector2i& offset, const ImageView2D& image)
Set cache image.
auto image() -> Image2D
Download cache image.

Private functions

auto doFeatures() const -> GlyphCacheFeatures pure virtual
Implementation for features()
void doSetImage(const Vector2i& offset, const ImageView2D& image) pure virtual
Implementation for setImage()
auto doImage() -> Image2D virtual
Implementation for image()

Function documentation

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

Constructor.

Parameters
size Glyph cache texture size
padding Padding around every glyph

std::pair<Vector2i, Range2Di> Magnum::Text::AbstractGlyphCache::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::AbstractGlyphCache::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::AbstractGlyphCache::insert(UnsignedInt glyph, const Vector2i& position, const Range2Di& rectangle)

Insert a glyph to the 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.

Use setImage() to upload an image corresponding to the glyphs.

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

Set cache image.

Uploads image for one or more glyphs to given offset in cache texture. The offset and ImageView::size() are expected to be in bounds for textureSize().

Image2D Magnum::Text::AbstractGlyphCache::image()

Download cache image.

Downloads the cache texture back. Calls doImage(). Available only if GlyphCacheFeature::ImageDownload is supported.

void Magnum::Text::AbstractGlyphCache::doSetImage(const Vector2i& offset, const ImageView2D& image) pure virtual private

Implementation for setImage()

The offset and ImageView::size() are guaranteed to be in bounds for textureSize().