◆ lay_out()

MAYAFLUX_API LayoutResult MayaFlux::Portal::Text::lay_out	(	std::string_view	text,
		GlyphAtlas &	atlas,
		float	pen_x = `0.F`,
		float	pen_y = `0.F`,
		uint32_t	wrap_w = `0`,
		uint32_t	tab_width = `4`
	)

Lay out a UTF-8 string into a sequence of screen-space quads.

Every codepoint this text needs is rasterized (cached, if not already) before any quad is emitted, so a GlyphAtlas growth triggered partway through this text cannot invalidate the UV coordinates already baked into quads emitted earlier in the same call. This guarantee is per-call only: a LayoutResult held across later, unrelated lay_out() calls on the same atlas is not protected if the atlas grows afterward from something else.

Every codepoint for which is_control() is true is never rasterized or counted as printable content. Among those, \t advances pen_x to the next tab stop and
advances pen_y by atlas.line_height() and resets pen_x; every other control codepoint (including \r) is skipped with no side effect. This is the same is_control() identification raw-string text handling uses; only the reaction to it differs here.

Consecutive non-control glyphs are kerned via FT_Get_Kerning() when the producing face (GlyphMetrics::face) has a kerning table. The previous glyph index resets to none across any control codepoint, across a wrap-induced line break, and whenever the producing face changes between consecutive glyphs: a glyph index is only meaningful within the face that assigned it, so a codepoint resolved through GlyphAtlas's fallback chain never gets kerned against a glyph from a different face.

Wrapping at wrap_w is a pure render-bounds guarantee, not word-aware line breaking: it breaks mid-word freely, with no whitespace lookback. This is deliberate - correctness here means no glyph ever renders past wrap_w, not that words stay intact. Each glyph is checked before it is placed, against its own advance width times a 1.5x margin, so the decision to wrap accounts for the glyph about to be drawn rather than reacting one glyph late to cumulative pen_x history - the margin absorbs the gap between a glyph's advance and its true rendered width so a glyph is never placed half past the boundary. A tab is checked the same way against its own tab-stop advance (no margin, since it draws nothing itself) immediately after computing its destination, not deferred to the next glyph's turn.

Bidirectional reordering and shaping are not performed. HarfBuzz slots in before the glyph index step when needed; the quad assembly loop and GlyphAtlas remain unchanged.

Each quad's byte_offset is the position of its codepoint's first byte in text, letting a caller correlate a quad back to source text (styling, hit-testing, extraction) without re-decoding UTF-8 itself.

Parameters

text	UTF-8 encoded input string.
atlas	GlyphAtlas to query and populate. May be modified (dirty flag set) if new glyphs are rasterized.
pen_x	Starting horizontal pen position in pixels.
pen_y	Starting vertical pen position in pixels (baseline).
wrap_w	Column to wrap at in pixels, or 0 to disable wrapping.
tab_width	Tab stop width in space-glyph-widths.

Returns: LayoutResult containing quads and final pen position.

Definition at line 22 of file TypeSetter.cpp.

{
    if (text.empty()) {
        return { .quads = {}, .final_pen_x = pen_x, .final_pen_y = pen_y };
    }
 
    LayoutResult out;
    out.quads.reserve(text.size());
 
    const float origin_x = 0.F;
 
    {
        const auto* prewarm_bytes = reinterpret_cast<const utf8proc_uint8_t*>(text.data());
        auto prewarm_remaining = static_cast<utf8proc_ssize_t>(text.size());
        utf8proc_ssize_t prewarm_offset = 0;
 
        while (prewarm_offset < prewarm_remaining) {
            utf8proc_int32_t prewarm_codepoint = 0;
            const utf8proc_ssize_t n = utf8proc_iterate(
                prewarm_bytes + prewarm_offset, prewarm_remaining - prewarm_offset, &prewarm_codepoint);
 
            if (n <= 0) {
                prewarm_offset += 1;
                continue;
            }
            prewarm_offset += n;
 
            if (prewarm_codepoint >= 0 && !is_control(static_cast<uint32_t>(prewarm_codepoint))) {
                atlas.get_or_rasterize(static_cast<FT_ULong>(prewarm_codepoint));
            }
        }
 
        if (tab_width > 0) {
            atlas.get_or_rasterize(static_cast<FT_ULong>(' '));
        }
    }
 
    FT_UInt prev_glyph_index = 0;
    const FontFace* prev_face = nullptr;
 
    constexpr float k_wrap_margin = 1.5F;
 
    const auto apply_wrap = [&](float upcoming_width) -> bool {
        if (wrap_w > 0 && pen_x + upcoming_width * k_wrap_margin > static_cast<float>(wrap_w)) {
            pen_x = origin_x;
            pen_y += static_cast<float>(atlas.line_height());
            prev_glyph_index = 0;
            prev_face = nullptr;
            return true;
        }
        return false;
    };
 
    const auto* bytes = reinterpret_cast<const utf8proc_uint8_t*>(text.data());
    auto remaining = static_cast<utf8proc_ssize_t>(text.size());
    utf8proc_ssize_t offset = 0;
 
    while (offset < remaining) {
        const auto codepoint_start = static_cast<size_t>(offset);
        utf8proc_int32_t codepoint = 0;
        const utf8proc_ssize_t n = utf8proc_iterate(bytes + offset, remaining - offset, &codepoint);
 
        if (n <= 0) {
            MF_WARN(Journal::Component::Portal, Journal::Context::API,
                "TypeSetter: invalid UTF-8 sequence at byte offset {}, skipping byte",
                static_cast<size_t>(offset));
            offset += 1;
            continue;
        }
 
        offset += n;
 
        if (codepoint < 0) {
            continue;
        }
 
        if (is_control(static_cast<uint32_t>(codepoint))) {
            if (codepoint == '\t' && tab_width > 0) {
                const GlyphMetrics* space = atlas.get_or_rasterize(static_cast<FT_ULong>(' '));
                const float stop_width = space && space->advance_x > 0
                    ? static_cast<float>(space->advance_x) * static_cast<float>(tab_width)
                    : 0.F;
 
                if (stop_width > 0.F) {
                    pen_x = (std::floor((pen_x - origin_x) / stop_width) + 1.F) * stop_width + origin_x;
                    apply_wrap(0.F);
                }
            } else if (codepoint == '\n') {
                pen_x = origin_x;
                pen_y += static_cast<float>(atlas.line_height());
            }
 
            prev_glyph_index = 0;
            prev_face = nullptr;
            continue;
        }
 
        const GlyphMetrics* m = atlas.get_or_rasterize(static_cast<FT_ULong>(codepoint));
        if (!m) {
            prev_glyph_index = 0;
            prev_face = nullptr;
            continue;
        }
 
        apply_wrap(static_cast<float>(m->advance_x));
 
        if (prev_face == m->face && prev_glyph_index != 0 && m->glyph_index != 0
            && m->face && FT_HAS_KERNING(m->face->get_face())) {
            FT_Vector delta {};
            FT_Get_Kerning(m->face->get_face(), prev_glyph_index, m->glyph_index, FT_KERNING_DEFAULT, &delta);
            pen_x += static_cast<float>(delta.x >> 6);
        }
 
        if (m->width > 0 && m->height > 0) {
            GlyphQuad q {};
            q.x0 = pen_x + static_cast<float>(m->bearing_x);
            q.y0 = pen_y - static_cast<float>(m->bearing_y);
            q.x1 = q.x0 + static_cast<float>(m->width);
            q.y1 = q.y0 + static_cast<float>(m->height);
            q.uv_x0 = m->uv_x0;
            q.uv_y0 = m->uv_y0;
            q.uv_x1 = m->uv_x1;
            q.codepoint = static_cast<uint32_t>(codepoint);
            q.uv_y1 = m->uv_y1;
            q.byte_offset = codepoint_start;
            out.quads.push_back(q);
        }
 
        pen_x += static_cast<float>(m->advance_x);
        prev_glyph_index = m->glyph_index;
        prev_face = m->face;
    }
 
    out.final_pen_x = pen_x;
    out.final_pen_y = pen_y;
    return out;
}

Referenced by create_layout(), impress(), MayaFlux::Portal::Text::TextRun::lay_out_text(), and x_at().

Here is the call graph for this function:

Here is the caller graph for this function: