On this page

Fonts and measuring

text_font.h is the backend neutral half of the text renderer. The widgets use it, and so can anything that wants glyphs without the element tree. Its results are bit identical to the old per backend walk, because the deck proofs depend on that.

Loading

text_font_load resolves the atlas beside the executable, the same rule isolen_app_desc::font follows. A loaded text_font owns the file bytes it points into until text_font_free. It holds up to TEXT_MAX_FACES (8) faces, the glyph and kern tables, the atlas size and pixels, and the metrics.

Lengths

Every call takes a byte length. Passing TEXT_FONT_TERMINATED walks to the NUL instead, and any other value is a byte count, so a slice of a larger buffer needs no copy.

Measuring, wrapping and eliding

  • text_font_measure returns the width of a run at a pixel size and tracking.
  • text_font_ascent, text_font_descent and text_font_line_height scale the metrics. The descent keeps its stored sign, so it is below zero.
  • text_font_min_width is the widest run that cannot break, which is the narrowest a column holding that text can go.
  • text_font_wrap breaks greedily on spaces and newlines into text_line offsets. A word wider than the width gets a line of its own. It returns the full line count even past cap.
  • text_font_elide cuts a run to fit a width and adds a ... mark. The output is always terminated.

A font can point fallback and fallback_handle at a second atlas for glyphs it lacks. Only the direction aware calls measure and draw those glyphs. The plain measure, wrap and elide skip a glyph the atlas lacks, exactly as the plain draw does, so the two always agree. For right to left text, bidi and Arabic shaping, see direction and bidi.

Wrap, elide and the minimum widthinteractive illustration
wrap, 4 lines
Gitty up walks the whole history
of a repository on one stage,
every branch and merge animated
from the commit graph.
elide
Gitty up walks the whole hist...
width 300 pxmin width 94 pxevery word fits
Drag the width down. text_font_wrap breaks greedily on spaces, and text_font_elide cuts the same run to one line with a mark. The dashed line is text_font_min_width, the widest word, which is the narrowest a column holding this text will go.
text_fonts.cpp
#include "isolenui/text/text_font.h"

// the atlas resolves beside the executable, the same rule
// isolen_app_desc::font follows
static bool boot_font(text_font* f)
{
    return text_font_load(f, "assets\\objectivity.atlas");
}

// TEXT_FONT_TERMINATED as the length walks to the nul, any other length is
// a byte count, so a slice of a larger buffer needs no copy
static void measure_caption(const text_font* f, const char* utf8, float width)
{
    const uint32_t face = 0u;
    const float px = 16.0f;
    const float tracking = 0.0f;

    const float full_w =
        text_font_measure(f, face, utf8, TEXT_FONT_TERMINATED, px, tracking);
    const float first_word_w = text_font_measure(f, face, utf8, 5u, px, tracking);

    // the widest run that cannot break, what a column must never go below
    const float floor_w =
        text_font_min_width(f, face, utf8, TEXT_FONT_TERMINATED, px, tracking);

    text_line lines[8];
    const uint32_t line_count = text_font_wrap(
        f, face, utf8, TEXT_FONT_TERMINATED, px, tracking, width, lines, 8u);
    const float block_h =
        float(line_count < 8u ? line_count : 8u) * text_font_line_height(f, px);

    char elided[64];
    text_font_elide(f, face, utf8, TEXT_FONT_TERMINATED, px, tracking, width,
                    elided, sizeof(elided));

    (void)full_w;
    (void)first_word_w;
    (void)floor_w;
    (void)block_h;
}

// a font that only measures can drop its atlas pixels, but one bound to a gfx
// device must keep them, a backend switch uploads the atlas again and
// gfx_font_bind refuses a font whose pixels are gone
static void measure_only(text_font* f)
{
    text_font_release_pixels(f);
    const float ascent = text_font_ascent(f, 24.0f);
    const float descent = text_font_descent(f, 24.0f);
    (void)ascent;
    (void)descent;
}

Releasing pixels

text_font_release_pixels frees the atlas bytes once they are on the gpu. The glyph and kern tables live in a separate block, so measuring and layout keep working.

A font bound to a gfx device must keep its pixels for as long as it stays bound. A backend switch uploads the atlas again, and replay fails for a font whose pixels are gone. gfx_font_bind refuses such a font outright, returning GFX_NONE and logging an error.

Last updated 6 October 2026