shaped_text.hpp

Go to the documentation of this file.

// shaped_text.hpp
//
// `ShapedText` is the canonical artifact produced by `TextRunPlanner::shape`.
// Measurement and paint paths are intended to consume this same artifact:
// measurement uses the per-run advances and line-break opportunities, while
// paint can walk the same runs, clusters, and eventual glyph buffers. Keeping
// the text artifact shared prevents layout and rendering from inventing
// incompatible segmentation rules.
//
// `TextRunPlanner` fills this structure with resolved font traces, bidi/script
// runs, UAX #29-lite grapheme clusters, heuristic line-break opportunities, and
// UTF-8 / UTF-16 / cluster index maps. Glyph buffers remain optional until the
// painting path asks SkShaper for per-glyph output.
 
#pragma once
 
#include "pulp/canvas/font_options.hpp"
#include "pulp/canvas/font_resolver.hpp"
 
#include <cstdint>
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::canvas {
 
// ── Metrics ──────────────────────────────────────────────────────────────

struct RunMetrics {
    float ascent  = 0.0f;
    float descent = 0.0f;
    float leading = 0.0f;
 
    float line_height() const noexcept { return ascent + descent + leading; }
};
 
// ── ShapedRun ────────────────────────────────────────────────────────────

struct ShapedRun {
    ResolvedFont font;            
    RunMetrics   metrics;
    std::uint8_t bidi_level = 0;  
    std::uint32_t script_tag = 0; 
    std::string  locale;          

    std::vector<std::uint16_t> glyph_ids;
    std::vector<float>         advances;
    std::vector<float>         offsets_x;
    std::vector<float>         offsets_y;
    std::vector<std::uint32_t> cluster_indices;

    std::size_t logical_start = 0;
    std::size_t logical_end   = 0;

    float advance_total = 0.0f;
};
 
// ── Clusters + line breaks ───────────────────────────────────────────────

struct ClusterEntry {
    std::uint32_t utf8_start  = 0;  
    std::uint32_t utf8_end    = 0;  
    std::uint32_t run_index   = 0;  
    std::uint32_t glyph_start = 0;  
    std::uint32_t glyph_count = 0;  
};

struct LineBreakOpportunity {
    std::uint32_t utf8_offset = 0;
    enum class Kind : std::uint8_t {
        Soft,  
        Hard,  
    } kind = Kind::Soft;
};
 
// ── Unicode index map ────────────────────────────────────────────────────

struct UnicodeIndexMap {
    std::vector<std::uint32_t> scalar_offsets;

    std::vector<std::uint32_t> utf16_offsets;

    std::vector<std::uint32_t> byte_to_cluster;
 
    std::size_t scalar_count() const noexcept {
        return scalar_offsets.empty() ? 0 : scalar_offsets.size() - 1;
    }
};
 
// ── ShapedText ───────────────────────────────────────────────────────────

struct ShapedText {
    std::string  text;     
    FontOptions  options;  
 
    std::vector<ShapedRun>           runs;
    std::vector<ClusterEntry>        clusters;
    std::vector<LineBreakOpportunity> line_breaks;
    UnicodeIndexMap                  index_map;

    float total_width = 0.0f;

    RunMetrics overall_metrics;
 
    bool empty() const noexcept { return runs.empty(); }
};
 
} // namespace pulp::canvas