font_options.hpp

Go to the documentation of this file.

// font_options.hpp
//
// `FontOptions` is the typed, hashable blob that replaces today's
// `(family_string, size, weight, slant)` tuple wherever the SDK needs to
// describe what font to use. Every cache in the font subsystem must key on
// the FULL blob, never on a subset — this single rule eliminates an entire
// class of "the cache returned the wrong thing because the key was too
// narrow" bugs (lifecycle invalidation, axis-instance cohabitation,
// per-feature cache splits, scope isolation).
//
// Deliberately NOT included in FontOptions:
//   * Paint position (x, y) — that's an argument to ShapedText::paint_at.
//   * TextAnchor — that's an argument to ShapedText::paint_at.
// Folding either into FontOptions would force every cache miss to re-shape
// on an anchor or position change. The `paint_at` API takes them separately so
// the same `ShapedText` artifact can paint at any anchor without re-shaping.
//
// This header is intentionally Skia-free so non-GPU translation units
// (e.g. `core/view/` widgets) can construct FontOptions without dragging
// the Skia headers in. The resolver layer (font_resolver.hpp) is the seam
// where Skia types are introduced.
 
#pragma once
 
#include <cstdint>
#include <functional>
#include <string>
#include <utility>
#include <vector>
 
namespace pulp::canvas {
 
// ── Enums ────────────────────────────────────────────────────────────────

enum class FontSlant : std::uint8_t {
    Normal,
    Italic,
    Oblique,
};

enum class BaseDirection : std::uint8_t {
    LTR,
    RTL,
    Auto,
};

enum class FallbackMode : std::uint8_t {
    Deterministic,
    Native,
    Hybrid,
};

enum class HintingMode : std::uint8_t {
    None,
    Slight,
    Normal,
    Full,
    PlatformDefault,
};

enum class AntiAliasMode : std::uint8_t {
    Default,
    LCD,
    Grayscale,
    NoAA,
};

enum class ColorFontMode : std::uint8_t {
    Auto,
    Bitmap,
    COLR,
    SVG,
    ForceMonochrome,
};
 
// ── Tag types ────────────────────────────────────────────────────────────

using FontFeatureTag = std::uint32_t;
 
constexpr FontFeatureTag make_font_feature_tag(char a, char b, char c, char d) {
    return (static_cast<std::uint32_t>(static_cast<unsigned char>(a)) << 24)
         | (static_cast<std::uint32_t>(static_cast<unsigned char>(b)) << 16)
         | (static_cast<std::uint32_t>(static_cast<unsigned char>(c)) <<  8)
         | (static_cast<std::uint32_t>(static_cast<unsigned char>(d)));
}

struct FontFeature {
    FontFeatureTag tag = 0;
    std::int32_t value = 0;
 
    constexpr bool operator==(const FontFeature& other) const noexcept {
        return tag == other.tag && value == other.value;
    }
};

using VariationAxisTag = std::uint32_t;
 
constexpr VariationAxisTag make_variation_axis_tag(char a, char b, char c, char d) {
    return make_font_feature_tag(a, b, c, d);
}
 
struct VariationAxis {
    VariationAxisTag tag = 0;
    float value = 0.0f;
 
    bool operator==(const VariationAxis& other) const noexcept {
        return tag == other.tag && value == other.value;
    }
};
 
// ── Synthesis policy ─────────────────────────────────────────────────────

struct FontSynthesisPolicy {
    bool weight = false;
    bool slant  = false;
    bool width  = false;
 
    bool operator==(const FontSynthesisPolicy&) const = default;
};
 
// ── Scope ────────────────────────────────────────────────────────────────

struct FontScopeId {
    enum class Kind : std::uint8_t { Global, Plugin, View };
 
    Kind kind = Kind::Global;
    std::uint64_t id = 0;
 
    static constexpr FontScopeId global() noexcept { return {Kind::Global, 0}; }
    static constexpr FontScopeId plugin(std::uint64_t plugin_id) noexcept {
        return {Kind::Plugin, plugin_id};
    }
    static constexpr FontScopeId view(std::uint64_t view_id) noexcept {
        return {Kind::View, view_id};
    }
 
    bool operator==(const FontScopeId&) const = default;
};
 
// ── FontOptions blob ─────────────────────────────────────────────────────

struct FontOptions {
    // ── Family + style ──────────────────────────────────────────────────
    std::vector<std::string> family_stack;

    float weight = 400.0f;

    float width = 100.0f;
 
    FontSlant slant = FontSlant::Normal;
    float oblique_angle = 0.0f;

    float size = 14.0f;
 
    // ── OpenType features ───────────────────────────────────────────────
    std::vector<FontFeature> features;
 
    // ── Variable-font axes ──────────────────────────────────────────────
    std::vector<VariationAxis> variation_axes;
 
    // ── Locale + direction ──────────────────────────────────────────────
    std::string locale;
    BaseDirection direction = BaseDirection::Auto;
 
 
    // ── Spacing ─────────────────────────────────────────────────────────
    float letter_spacing = 0.0f;
    float word_spacing = 0.0f;
 
    // ── Render policy ───────────────────────────────────────────────────
    HintingMode    hinting_mode    = HintingMode::PlatformDefault;
    AntiAliasMode  aa_mode         = AntiAliasMode::Default;
    ColorFontMode  color_font_mode = ColorFontMode::Auto;
 
    // ── Synthesis policy ────────────────────────────────────────────────
    FontSynthesisPolicy font_synthesis;
 
    // ── Resolver behavior ───────────────────────────────────────────────
    FallbackMode fallback_mode = FallbackMode::Hybrid;
    FontScopeId  scope         = FontScopeId::global();

    std::uint64_t registry_generation = 0;
 
    bool operator==(const FontOptions&) const = default;

    std::size_t hash() const noexcept;
};
 
} // namespace pulp::canvas
 
namespace std {
template <>
struct hash<pulp::canvas::FontOptions> {
    std::size_t operator()(const pulp::canvas::FontOptions& opts) const noexcept {
        return opts.hash();
    }
};
template <>
struct hash<pulp::canvas::FontScopeId> {
    std::size_t operator()(const pulp::canvas::FontScopeId& id) const noexcept {
        return (std::hash<std::uint64_t>{}(id.id) << 2)
             ^ std::hash<std::uint8_t>{}(static_cast<std::uint8_t>(id.kind));
    }
};
} // namespace std