font_resolver.hpp

Go to the documentation of this file.

// font_resolver.hpp
//
// `FontResolver` is the canonical resolution path: one parser, one
// cascade, one set of fallback semantics. Every text-rendering or text-
// measurement caller in the SDK (SkiaCanvas, TextShaper, bundled_fonts,
// sdf_atlas, examples/ui-preview, the JS web-compat layer) talks to
// this resolver. Legacy split parsers/cascades are kept out of the
// public paint and measurement paths.
//
// The resolver returns a `ResolvedFont` describing not just the chosen
// typeface but also *how* it was chosen: which scope owned it, which
// step of the cascade matched, whether faux-synthesis was applied. That
// trace data feeds the `FontFlightRecorder` and missing-font advice.
//
// This header forward-declares `SkTypeface`; the implementation pulls
// in Skia. Non-GPU translation units can include this header to obtain
// a `ResolvedFont` value without dragging Skia in — the typeface field
// is opaque via `ResolvedFont::has_typeface()`.
 
#pragma once
 
#include "pulp/canvas/font_options.hpp"
 
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
#ifdef PULP_HAS_SKIA
#include "include/core/SkFont.h"
#include "include/core/SkFontTypes.h"
#include "include/core/SkRefCnt.h"
class SkTypeface;
#endif
 
namespace pulp::canvas {

std::string platform_family_for_css_generic(const std::string& css_family);

void set_css_generic_family_override(const std::string& keyword, const std::string& family);

struct CssFontFamily {
    std::string name;    
    bool quoted = false; 
};

CssFontFamily parse_css_font_family(std::string_view entry);

std::vector<std::string> split_css_font_family_list(std::string_view list);

bool paragraph_fakes_missing_font_styles(std::string_view css_font_family, int weight, int slant);

std::string platform_family_for_css_family(std::string_view entry);

bool platform_face_is_family(std::string_view platform_family, std::string_view actual_family);
 
#ifdef PULP_HAS_SKIA
 
// ── AA / hinting policy ─────────────────────────────────────────────────
//
// Pure enum-to-enum translation from the platform-neutral FontOptions modes
// (HintingMode, AntiAliasMode) to Skia's paint flags (SkFont::Edging,
// SkFontHinting). Centralised here so every Skia-backed paint path —
// SkiaCanvas, TextShaper, SDF glyph atlas — pulls the same policy out of
// the resolver instead of inventing its own mapping. Stateless and
// branch-free; safe to call from the audio thread (no allocations, no
// locks, no Skia globals touched).
//
// Mapping rules (locked by test_font_aa_hinting):
//   * AntiAliasMode::Default     → nullopt (caller keeps the
//                                  opacity-layer text edging heuristic).
//   * AntiAliasMode::LCD         → kSubpixelAntiAlias
//   * AntiAliasMode::Grayscale   → kAntiAlias
//   * AntiAliasMode::NoAA        → kAlias
//
//   * HintingMode::PlatformDefault → nullopt (caller preserves the
//                                     backend/platform default).
//   * HintingMode::None            → kNone
//   * HintingMode::Slight          → kSlight
//   * HintingMode::Normal          → kNormal
//   * HintingMode::Full            → kFull
 
// `AntiAliasMode::Default` follows the caller's opacity-layer text edging
// heuristic, and `HintingMode::PlatformDefault` preserves the backend's own
// default. Hard-coding either to a single Skia value erases the per-caller
// branch.
//
// Both helpers now return `std::optional`: `Default` / `PlatformDefault`
// resolve to `nullopt` ("caller decides"); explicit modes resolve to the
// fixed Skia enum. The convenience `ResolvedFont::sk_edging()` /
// `sk_hinting()` accessors below preserve that optional result so
// callers can keep their own opacity / backend-default branches intact.
 
constexpr std::optional<SkFont::Edging> sk_edging_for(AntiAliasMode mode) noexcept {
    switch (mode) {
        case AntiAliasMode::LCD:       return SkFont::Edging::kSubpixelAntiAlias;
        case AntiAliasMode::Grayscale: return SkFont::Edging::kAntiAlias;
        case AntiAliasMode::NoAA:      return SkFont::Edging::kAlias;
        case AntiAliasMode::Default:   return std::nullopt;
    }
    return std::nullopt;
}
 
constexpr std::optional<SkFontHinting> sk_hinting_for(HintingMode mode) noexcept {
    switch (mode) {
        case HintingMode::None:            return SkFontHinting::kNone;
        case HintingMode::Slight:          return SkFontHinting::kSlight;
        case HintingMode::Normal:          return SkFontHinting::kNormal;
        case HintingMode::Full:            return SkFontHinting::kFull;
        case HintingMode::PlatformDefault: return std::nullopt;
    }
    return std::nullopt;
}
 
#endif  // PULP_HAS_SKIA
 
// ── Trace types ──────────────────────────────────────────────────────────

enum class FallbackOrigin : std::uint8_t {
    ScopeView,    
    ScopePlugin,  
    ScopeGlobal,  
    Bundled,      
    Platform,     
    PlatformChar, 
    Synthetic,    
    NotFound,     
};
 
const char* to_string(FallbackOrigin) noexcept;
 
struct FallbackTraceStep {
    std::string    requested_family;  
    FallbackOrigin origin;            
    bool           succeeded;         
    std::string    selected_family;   
    std::string    note;              
};
 
struct SynthesisTrace {
    bool        faux_bold   = false;
    bool        faux_italic = false;
    bool        faux_width  = false;
    std::string source_family;  
};
 
// ── ResolvedFont ─────────────────────────────────────────────────────────

std::string resolved_face_identity(const std::string& css_font_family,
                                   float weight,
                                   FontSlant slant = FontSlant::Normal);
 
struct ResolvedFont {
#ifdef PULP_HAS_SKIA
    sk_sp<SkTypeface> typeface;
#endif
 
    std::string    actual_family;      
    FallbackOrigin origin = FallbackOrigin::NotFound;
    FontScopeId    scope;
    std::uint64_t  generation = 0;     
 
    std::vector<FallbackTraceStep> trace;
    SynthesisTrace                 synthesis;

    AntiAliasMode aa_mode      = AntiAliasMode::Default;
    HintingMode   hinting_mode = HintingMode::PlatformDefault;

    ColorFontMode color_font_mode = ColorFontMode::Auto;
 
    bool has_typeface() const noexcept {
#ifdef PULP_HAS_SKIA
        return static_cast<bool>(typeface);
#else
        return false;
#endif
    }
 
    bool resolved() const noexcept {
        return origin != FallbackOrigin::NotFound;
    }
 
#ifdef PULP_HAS_SKIA
    std::optional<SkFont::Edging> sk_edging() const noexcept {
        return sk_edging_for(aa_mode);
    }

    std::optional<SkFontHinting> sk_hinting() const noexcept {
        return sk_hinting_for(hinting_mode);
    }
#endif

    bool supports_color_font() const noexcept;

    bool color_font_active() const noexcept;
};
 
// ── FontResolver ─────────────────────────────────────────────────────────
 
class FontResolver {
public:
    static FontResolver& instance();

    ResolvedFont resolve_family_list(const FontOptions& options);

    ResolvedFont resolve_character_fallback(const FontOptions& options,
                                            const ResolvedFont& primary,
                                            std::uint32_t codepoint);

    void clear_cache();

    void set_cache_capacity(std::size_t entries);
    std::size_t cache_capacity() const noexcept;

    std::size_t cache_size() const noexcept;

    struct Impl;
 
private:
    FontResolver();
    ~FontResolver();
    FontResolver(const FontResolver&) = delete;
    FontResolver& operator=(const FontResolver&) = delete;
 
    std::unique_ptr<Impl> impl_;
};
 
} // namespace pulp::canvas