This is a snapshot of a work-in-progress documentation theme. If you feel lost, miss something, or want to see the original Doxygen docs instead, head over to the archived version of this documentation page.

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 plugin manager
std::unique_ptr<Text::AbstractFont> font;

// Configured glyph cache
Text::GlyphCache cache;

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

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

// Draw the text on the screen
shader.setTransformationProjectionMatrix(projection)
    .setColor(Color3(1.0f))
    .setVectorTexture(glyphCache->texture());
mesh.draw(shader);

See render(AbstractFont&, const GlyphCache&, Float, const std::string&, Alignment) and render(AbstractFont&, const GlyphCache&, Float, const std::string&, Buffer&, Buffer&, 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:

std::unique_ptr<Text::AbstractFont> font;
Text::GlyphCache cache;
Shaders::Vector2D shader;

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

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

// Draw the text on the screen
shader.setTransformationProjectionMatrix(projection)
    .setColor(Color3(1.0f))
    .setVectorTexture(glyphCache->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 neither EXT_map_buffer_range nor CHROMIUM_map_sub 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, Buffer& vertexBuffer, Buffer& indexBuffer, BufferUsage usage, Alignment alignment = Alignment::LineLeft) -> std::tuple<Mesh, Range2D>
Render text.
static auto render() -> std::tuple<std::vector<Vector2>, std::vector<Vector2>, std::vector<UnsignedInt>, 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

Public functions

void render()
Render text.

Function documentation

template<UnsignedInt dimensions>
static std::tuple<Mesh, Range2D> Magnum::Text::Renderer<dimensions>::render(AbstractFont& font, const GlyphCache& cache, Float size, const std::string& text, Buffer& vertexBuffer, Buffer& indexBuffer, 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>
static std::tuple<std::vector<Vector2>, std::vector<Vector2>, std::vector<UnsignedInt>, Range2D> Magnum::Text::Renderer<dimensions>::render()

Render text.

Returns tuple with vertex positions, texture coordinates, indices 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.

template<UnsignedInt dimensions>
void Magnum::Text::Renderer<dimensions>::render()

Render text.

Renders the text to vertex buffer, reusing index buffer already filled with reserve(). Rectangle spanning the rendered text is available through rectangle().

Initially no text is rendered.