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

OpenGL glyph cache.

Contains font glyphs rendered into a texture atlas.

Usage

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

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

Text::GlyphCacheGL cache{PixelFormat::R8Unorm, Vector2i{128}};
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 GL::TextureFormat used by texture() is implicitly coming from GL::textureFormat(Magnum::PixelFormat) applied to format(), or if GlyphCacheFeature::ImageProcessing is supported, to processedFormat() instead.

If PixelFormat::R8Unorm is used for format() or if GlyphCacheFeature::ImageProcessing is supported and PixelFormat::R8Unorm is used for processedFormat(), on desktop OpenGL the class expects that ARB_texture_rg (OpenGL 3.0) is supported and uses GL::TextureFormat::R8. On OpenGL ES 2.0, if EXT_texture_rg is supported, GL::TextureFormat::Red / GL::TextureFormat::R8 is used instead of GL::TextureFormat::Luminance for PixelFormat::R8Unorm. On WebGL 1 GL::TextureFormat::Luminance is used for PixelFormat::R8Unorm always.

While this is abstracted away to not affect common use through image(), processedImage() or setProcessedImage(), code interacting directly with 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.

Base classes

class AbstractGlyphCache new in 2019.10: Base for glyph caches.

Derived classes

class DistanceFieldGlyphCacheGL new in Git master: OpenGL glyph cache with distance field rendering.

Constructors, destructors, conversion operators

GlyphCacheGL(PixelFormat format, const Vector2i& size, const Vector2i& padding = Vector2i{1}) explicit new in Git master: Constructor.
GlyphCacheGL(GL::TextureFormat internalFormat, const Vector2i& size, const Vector2i& padding = Vector2i{1}) deprecated in Git master explicit: Constructor.
GlyphCacheGL(GL::TextureFormat internalFormat, const Vector2i& size, const Vector2i& processedSize, const Vector2i& padding) deprecated in Git master explicit: Construct with a specific processed size.
GlyphCacheGL(const Vector2i& size, const Vector2i& padding = Vector2i{1}) deprecated in Git master explicit: Construct with an implicit format.
GlyphCacheGL(const Vector2i& size, const Vector2i& processedSize, const Vector2i& padding) deprecated in Git master explicit: Construct with an implicit format and a specific processed size.
GlyphCacheGL(NoCreateT) explicit noexcept new in Git master: Construct without creating the internal state and the OpenGL texture object.
GlyphCacheGL(PixelFormat format, const Vector2i& size, PixelFormat processedFormat, const Vector2i& processedSize, const Vector2i& padding = Vector2i{1}) protected explicit new in Git master: Construct with a specific processed format and size.

Public functions

auto texture() -> GL::Texture2D&: Cache texture.

Function documentation

Magnum::Text::GlyphCacheGL::GlyphCacheGL(PixelFormat format, const Vector2i& size, const Vector2i& padding = Vector2i{1}) explicit new in Git master

Constructor.

Parameters
format	Source image format
size	Source image size size in pixels
padding	Padding around every glyph in pixels

The size is expected to be non-zero. If the implementation advertises GlyphCacheFeature::ImageProcessing, the processedFormat() and processedSize() is the same as format and size, use AbstractGlyphCache(PixelFormat, const Vector3i&, PixelFormat, const Vector2i&, const Vector2i&) to specify different values.

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

Constructor.

Magnum::Text::GlyphCacheGL::GlyphCacheGL(GL::TextureFormat internalFormat, const Vector2i& size, const Vector2i& processedSize, const Vector2i& padding) explicit

Construct with a specific processed size.

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

Construct with an implicit format.

Calls GlyphCacheGL(PixelFormat, const Vector2i&, const Vector2i&) with format set to PixelFormat::R8Unorm.

Magnum::Text::GlyphCacheGL::GlyphCacheGL(const Vector2i& size, const Vector2i& processedSize, const Vector2i& padding) explicit

Construct with an implicit format and a specific processed size.

Calls GlyphCacheGL(PixelFormat, const Vector2i&, PixelFormat, const Vector2i&, const Vector2i&) with format and processedFormat set to PixelFormat::R8Unorm.

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

Magnum::Text::GlyphCacheGL::GlyphCacheGL(PixelFormat format, const Vector2i& size, PixelFormat processedFormat, const Vector2i& processedSize, const Vector2i& padding = Vector2i{1}) explicit protected new in Git master

Construct with a specific processed format and size.

Parameters
format	Source image format
size	Source image size size in pixels
processedFormat	Processed image format
processedSize	Processed glyph cache texture size in pixels
padding	Padding around every glyph in pixels. See Glyph padding for more information about the default.

The size and processedSize is expected to be non-zero. All glyphs are saved in format relative to size and with padding, although the actual glyph cache texture is in processedFormat and has processedSize.

Meant to be only used by subclasses that advertise GlyphCacheFeature::ImageProcessing and reimplement AbstractGlyphCache::doSetImage() to take the differences between format, size and processedFormat, processedSize into account.