Magnum::Text::AbstractRenderer class

OpenGL 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 = ;

/* Open a 12 pt font */
font->openFile("font.ttf", 12.0f);

/* Populate a glyph cache */
Text::GlyphCacheGL cache{PixelFormat::R8Unorm, Vector2i{128}};
font->fillGlyphCache(cache, "abcdefghijklmnopqrstuvwxyz"
                            "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
                            "0123456789?!:;,. ");

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

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

/* Projection matrix is matching application window size to have the size match
   12 pt in other applications, assuming a 96 DPI display and no UI scaling. */
Matrix3 projectionMatrix = Matrix3::projection(Vector2{windowSize()});

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

See render(AbstractFont&, const AbstractGlyphCache&, Float, const std::string&, Alignment) and render(AbstractFont&, const AbstractGlyphCache&, 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, 12.0f, 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())
    .draw(renderer.mesh());

Public static functions

static auto render(AbstractFont& font, const AbstractGlyphCache& cache, Float size, const std::string& text, Alignment alignment = Alignment::LineLeft) -> std::tuple<std::vector<Vector2>, std::vector<Vector2>, std::vector<UnsignedInt>, Range2D>
Render text.
static auto render(AbstractFont& font, const AbstractGlyphCache& 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

AbstractRenderer(AbstractFont& font, const AbstractGlyphCache& cache, Float size, Alignment alignment = Alignment::LineLeft) explicit
Constructor.
AbstractRenderer(AbstractFont&, AbstractGlyphCache&&, Float, Alignment alignment = Alignment::LineLeft) deleted explicit
AbstractRenderer(AbstractRenderer&) deleted
Copying is not allowed.
AbstractRenderer(AbstractRenderer&&) noexcept
Move constructor.

Public functions

auto operator=(AbstractRenderer&) -> AbstractRenderer& deleted
Copying is not allowed.
auto operator=(AbstractRenderer&&) -> AbstractRenderer& deleted
Move assignment is not allowed.
auto capacity() const -> UnsignedInt
Capacity for rendered glyphs.
auto fontSize() const -> Float new in Git master
Font size in points.
auto rectangle() const -> Range2D
Rectangle spanning the rendered text.
auto vertexBuffer() -> GL::Buffer&
Vertex buffer.
auto indexBuffer() -> GL::Buffer&
Index buffer.
auto mesh() -> GL::Mesh&
Mesh.
void reserve(UnsignedInt glyphCount, GL::BufferUsage vertexBufferUsage, GL::BufferUsage indexBufferUsage)
Reserve capacity for rendered glyphs.
void render(const std::string& text)
Render text.

Function documentation

static std::tuple<std::vector<Vector2>, std::vector<Vector2>, std::vector<UnsignedInt>, Range2D> Magnum::Text::AbstractRenderer::render(AbstractFont& font, const AbstractGlyphCache& cache, Float size, const std::string& text, Alignment alignment = Alignment::LineLeft)

Render text.

Parameters
font Font
cache Glyph cache
size Font size in points
text Text to render
alignment Text alignment

Returns a tuple with vertex positions, texture coordinates, indices and rectangle spanning the rendered text. Expects that font is present in cache and that cache isn't an array.

static std::tuple<GL::Mesh, Range2D> Magnum::Text::AbstractRenderer::render(AbstractFont& font, const AbstractGlyphCache& 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 Ignored, provided just for backward compatibility
alignment Text alignment

Returns a mesh prepared for use with Shaders::VectorGL or Shaders::DistanceFieldVectorGL and a rectangle spanning the rendered text. Expects that font is present in cache and that cache isn't an array.

Magnum::Text::AbstractRenderer::AbstractRenderer(AbstractFont& font, const AbstractGlyphCache& cache, Float size, Alignment alignment = Alignment::LineLeft) explicit

Constructor.

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

Expects that font is present in cache and that cache isn't an array.

Magnum::Text::AbstractRenderer::AbstractRenderer(AbstractFont&, AbstractGlyphCache&&, Float, Alignment alignment = Alignment::LineLeft) explicit deleted

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

Magnum::Text::AbstractRenderer::AbstractRenderer(AbstractRenderer&&) noexcept

Move constructor.

Performs a destructive move, i.e. the original object isn't usable afterwards anymore.

UnsignedInt Magnum::Text::AbstractRenderer::capacity() const

Capacity for rendered glyphs.

void Magnum::Text::AbstractRenderer::reserve(UnsignedInt glyphCount, GL::BufferUsage vertexBufferUsage, GL::BufferUsage indexBufferUsage)

Reserve capacity for rendered glyphs.

Reallocates memory in buffers to hold glyphCount glyphs and prefills index buffer. The vertexBufferUsage and indexBufferUsage parameters are ignored and provided just for backward compatibility.

Initially zero capacity is reserved.

void Magnum::Text::AbstractRenderer::render(const std::string& text)

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.