template<UnsignedInt dimensions>
Magnum::Text::Renderer class

Text renderer.

Lays out the text into mesh using given font. Use of ligatures, kerning etc. depends on features supported by particular font and its layouter.

Usage

Immutable text (e.g. menu items, credits) can be simply rendered using static methods, returning result either as data arrays or as fully configured mesh. The text can be then drawn as usual by configuring the shader and drawing the mesh:

/* Font instance, received from a plugin manager */
Containers::Pointer<Text::AbstractFont> font;

/* Configured glyph cache */
Text::GlyphCache cache{Vector2i{512}};
font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz"
                            "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
                            "0123456789?!:;,. ");

Shaders::Vector2D shader;
GL::Buffer vertexBuffer, indexBuffer;
GL::Mesh mesh;

/* Render the text, centered */
std::tie(mesh, std::ignore) = Text::Renderer2D::render(*font, cache, 0.15f,
    "Hello World!", vertexBuffer, indexBuffer, GL::BufferUsage::StaticDraw,
    Text::Alignment::LineCenter);

/* Draw the text on the screen */
shader.setTransformationProjectionMatrix(projectionMatrix)
    .setColor(0xffffff_rgbf)
    .bindVectorTexture(cache.texture());
mesh.draw(shader);

See render(AbstractFont&, const GlyphCache&, Float, const std::string&, Alignment) and render(AbstractFont&, const GlyphCache&, Float, const std::string&, GL::Buffer&, GL::Buffer&, GL::BufferUsage, Alignment) for more information.

While this method is sufficient for one-shot rendering of static texts, for mutable texts (e.g. FPS counters, chat messages) there is another approach that doesn't recreate everything on each text change:

/* Initialize the renderer and reserve memory for enough glyphs */
Text::Renderer2D renderer{*font, cache, 0.15f, Text::Alignment::LineCenter};
renderer.reserve(32, GL::BufferUsage::DynamicDraw, GL::BufferUsage::StaticDraw);

/* Update the text occasionally */
renderer.render("Hello World Countdown: 10");

/* Draw the text on the screen */
shader.setTransformationProjectionMatrix(projectionMatrix)
    .setColor(0xffffff_rgbf)
    .bindVectorTexture(cache.texture());
renderer.mesh().draw(shader);

Required OpenGL functionality

Mutable text rendering requires ARB_map_buffer_range on desktop OpenGL (also part of OpenGL ES 3.0). If EXT_map_buffer_range is not available in ES 2.0, at least OES_mapbuffer must be supported for asynchronous buffer updates. There is no similar extension in WebGL, thus plain (and slow) buffer updates are used there.

Base classes

class AbstractRenderer
Base for text renderers.

Public static functions

static auto render(AbstractFont& font, const GlyphCache& cache, Float size, const std::string& text, GL::Buffer& vertexBuffer, GL::Buffer& indexBuffer, GL::BufferUsage usage, Alignment alignment = Alignment::LineLeft) -> std::tuple<GL::Mesh, Range2D>
Render text.

Constructors, destructors, conversion operators

Renderer(AbstractFont& font, const GlyphCache& cache, Float size, Alignment alignment = Alignment::LineLeft) explicit
Constructor.
Renderer(AbstractFont&, GlyphCache&&, Float, Alignment alignment = Alignment::LineLeft) deleted

Function documentation

template<UnsignedInt dimensions>
static std::tuple<GL::Mesh, Range2D> Magnum::Text::Renderer<dimensions>::render(AbstractFont& font, const GlyphCache& cache, Float size, const std::string& text, GL::Buffer& vertexBuffer, GL::Buffer& indexBuffer, GL::BufferUsage usage, Alignment alignment = Alignment::LineLeft)

Render text.

Parameters
font Font
cache Glyph cache
size Font size
text Text to render
vertexBuffer Buffer where to store vertices
indexBuffer Buffer where to store indices
usage Usage of vertex and index buffer
alignment Text alignment

Returns mesh prepared for use with Shaders::AbstractVector subclasses and rectangle spanning the rendered text.

template<UnsignedInt dimensions>
Magnum::Text::Renderer<dimensions>::Renderer(AbstractFont& font, const GlyphCache& cache, Float size, Alignment alignment = Alignment::LineLeft) explicit

Constructor.

Parameters
font Font
cache Glyph cache
size Font size
alignment Text alignment

template<UnsignedInt dimensions>
Magnum::Text::Renderer<dimensions>::Renderer(AbstractFont&, GlyphCache&&, Float, Alignment alignment = Alignment::LineLeft) deleted

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.