text_shaper.hpp

Go to the documentation of this file.

#pragma once
 
// TextShaper — measure-once, reflow-forever text layout.
// Inspired by Cheng Lou's PreText pattern: expensive text shaping runs once,
// then line breaking uses just arithmetic over cached segment widths.
//
// Default ON when PULP_TEXT_SHAPING is enabled (requires Skia with SkParagraph).
// Falls back to character-width estimation when disabled.
 
#include <pulp/canvas/canvas.hpp>
#include <pulp/canvas/attributed_string.hpp>
#include <string>
#include <string_view>
#include <vector>
#include <unordered_map>
#include <memory>
#include <cstdint>
#include <mutex>
 
namespace pulp::canvas {

struct ShapedSegment {
    std::string text;
    float width = 0;            // Measured width in pixels
    float ascent = 0;           // Distance above baseline
    float descent = 0;          // Distance below baseline
    float leading = 0;          // Extra inter-line gap
    bool is_whitespace = false;  // Can break here
    bool is_newline = false;     // Hard line break
    // This segment begins in the same logical word as its predecessor. Rich
    // text style boundaries are not CSS line-break opportunities.
    bool joins_previous_word = false;
    int style_index = -1;        // AttributedString span; -1 for plain text
};

class PreparedText {
public:
    PreparedText() = default;

    const std::vector<ShapedSegment>& segments() const { return segments_; }

    float line_height() const { return line_height_; }

    float ascent()  const { return ascent_; }
    float descent() const { return descent_; }
    float leading() const { return leading_; }
    bool metrics_are_real() const { return metrics_real_; }

    float typographic_ascent() const {
        return typographic_ascent_;
    }
    float typographic_descent() const {
        return typographic_descent_;
    }

    int font_weight() const { return font_weight_; }

    float total_width() const;

    bool empty() const { return segments_.empty(); }
 
private:
    friend class TextShaper;
    std::vector<ShapedSegment> segments_;
    float line_height_ = 0;
    float ascent_ = 0;
    float descent_ = 0;
    float leading_ = 0;
    float typographic_ascent_ = 0;
    float typographic_descent_ = 0;
    bool metrics_real_ = false;
    std::string font_family_;
    float font_size_ = 0;
    int font_weight_ = 400;
};

struct ShapedLayout {
    struct Line {
        struct Fragment {
            std::string text;
            float width = 0;
            int style_index = -1;
        };
 
        float width = 0;
        float y = 0;
        float ascent = 0;
        float descent = 0;
        float leading = 0;
        float height = 0;
        float x_offset = 0;
        int first_segment = 0;
        int segment_count = 0;
        std::string text;  // Materialized line text (optional)
        // Exact styled pieces on this line. Populated by
        // layout_with_lines(); empty for the allocation-free layout() path.
        // Unlike first_segment/segment_count this also represents fragments
        // created by break-word/anywhere inside one shaped segment.
        std::vector<Fragment> fragments;
    };
 
    std::vector<Line> lines;
    float total_width = 0;
    float total_height = 0;
    int line_count = 0;
};

enum class BreakMode {
    normal,
    break_word,
    anywhere,
};

class TextShaper {
public:
    TextShaper();
    ~TextShaper();

    PreparedText prepare(
        std::string_view text, std::string_view font_family, float font_size,
        int font_weight = 400, int font_slant = 0,
        float letter_spacing = 0.0f,
        const std::vector<Canvas::FontFeature>& font_features = {});

    PreparedText prepare(
        const AttributedString& text,
        const std::vector<Canvas::FontFeature>& font_features = {});

    ShapedLayout layout(const PreparedText& prepared, float max_width,
                        float line_height = 0, int max_lines = 0,
                        BreakMode break_mode = BreakMode::normal) const;

    ShapedLayout layout_with_lines(const PreparedText& prepared, float max_width,
                                    float line_height = 0, int max_lines = 0,
                                    BreakMode break_mode = BreakMode::normal) const;

    float measure_height(const PreparedText& prepared, float max_width,
                         float line_height = 0) const;

    int count_lines(const PreparedText& prepared, float max_width) const;

    void clear_cache();

    bool uses_real_shaping() const;
 
private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};

struct ParagraphLineExtent {
    float ascent = 0.0f;
    float descent = 0.0f;
    float height = 0.0f;
};

struct ParagraphTextExtents {
    float ascent = 0.0f;
    float descent = 0.0f;
    float leading = 0.0f; 
    bool real = false;    
 
    float line_height() const {
        return ascent + descent + leading;
    }
};

ParagraphTextExtents paragraph_text_extents(const std::vector<ParagraphLineExtent>& lines,
                                            float font_size);

TextShaper& global_text_shaper();

std::uint64_t text_shaper_prepare_call_count();
 
}  // namespace pulp::canvas