bundled_fonts.hpp

Go to the documentation of this file.

// bundled_fonts.hpp
//
// Pulp ships a small set of curated fonts under `external/fonts/` so plugin UIs
// can render deterministically without depending on what happens to be
// installed system-wide. Those .ttf files are baked into `pulp-canvas` at
// build time (see core/canvas/CMakeLists.txt → pulp_add_binary_data) and this
// module makes them visible to Skia's font lookup path.
//
// The Skia prebuilt binaries shipped via skia-builder are linked without
// FreeType/Fontations, which means `SkFontMgr_New_Custom_Data` is not exported
// from libskia.a. Instead we go one rung lower: use the *platform* font
// manager (CoreText / DirectWrite / fontconfig / Android) to materialise the
// bundled .ttfs into `SkTypeface`s via `SkFontMgr::makeFromData`, and cache
// those typefaces by family name. Callers can then ask for the bundled face
// before falling back to a `matchFamilyStyle` query that depends on the host
// system.
//
// The embedded families are materialized through Skia on first lookup so
// `canvas.set_font("JetBrains Mono", ...)` succeeds even on machines that
// do not have JetBrains Mono installed system-wide.
//
// On Apple platforms the same faces are also kept in a CoreText registry, which
// the CoreGraphics canvas paints with and, without Skia, TextShaper measures
// with. Elsewhere, without Skia, bundled-font registration is a no-op.
 
#pragma once
 
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <future>
#include <string>
#include <optional>
#include <vector>
 
#ifdef PULP_HAS_SKIA
#include "include/core/SkFontStyle.h"
#include "include/core/SkRefCnt.h"
class SkFontMgr;
class SkTypeface;
#endif
 
namespace pulp::canvas {
 
// ── Public font-registration API ─────────────────────────────────────────
// Plugin authors bundle their own .ttf/.otf files (e.g. via the CMake
// `pulp_register_font(target NAME path/to/font.ttf [FAMILY "..."])` macro
// or by hand-rolling pulp_add_binary_data) and call `register_font(...)`
// during plugin startup so subsequent `canvas.set_font("My Family", ...)`
// and `setFontFamily(label, "My Family")` calls resolve to the supplied
// face instead of silently falling back to the platform font manager.
//
// These entry points are available regardless of `PULP_HAS_SKIA`. On Apple
// platforms every registration also reaches the CoreText registry; without
// Skia that is the only registry, and `register_font` succeeds when CoreText
// can read the bytes. On other platforms without Skia they degrade to a no-op
// that returns `false`, which lets plugin startup code call them
// unconditionally.

bool register_font(const std::uint8_t* data, std::size_t size,
                   const std::string& family_override = "");

bool register_font_file(const std::string& path,
                        const std::string& family_override = "");

struct DeclaredWeightRange {
    int min = 400;
    int max = 400;
};

void declare_font_face_weight_range(const std::string& family, int weight_min, int weight_max,
                                    const std::string& scope = {});

void clear_declared_font_face_weight_ranges(const std::string& scope);

bool has_declared_font_face_weights(const std::string& family);

int css_match_declared_weight(const std::vector<DeclaredWeightRange>& ranges, int desired_weight);

std::optional<bool> declared_face_synthesizes_bold(const std::string& family, int requested_weight);

std::uint64_t woff2_file_routes() noexcept;

bool is_font_registered(const std::string& family);

std::uint64_t font_registration_generation() noexcept;

void bump_font_registration_generation() noexcept;
 
// ── Async lifecycle + font validation ────────────────────────────────────

enum class FontState : std::uint8_t {
    Pending,
    Loaded,
    Failed,
    Substituted,
};

bool validate_font_bytes(const std::uint8_t* data, std::size_t size);

std::future<FontState> register_font_url(const std::string& url,
                                         const std::string& family_override = "");
 
// ── Compressed fonts + text boundary helpers ─────────────────────────────

bool register_font_woff2(const std::uint8_t* woff2_data, std::size_t size,
                         const std::string& family_override = "");

bool woff2_decoder_available() noexcept;

std::size_t cluster_step(const std::string& text, std::size_t byte_offset,
                         bool forward = true);

std::size_t word_break_step(const std::string& text,
                            std::size_t byte_offset,
                            const std::string& locale = "",
                            bool forward = true);

std::vector<std::size_t> line_break_opportunities(const std::string& text,
                                                  const std::string& locale = "");
 
#ifdef PULP_HAS_SKIA

sk_sp<SkFontMgr> platform_font_manager();

sk_sp<SkTypeface> match_bundled_typeface(SkFontMgr* mgr,
                                         const std::string& family,
                                         SkFontStyle style);

sk_sp<SkTypeface> match_registered_typeface(const std::string& family,
                                            SkFontStyle style);

bool face_wght_axis(const SkTypeface* face,
                    float& out_min, float& out_max, float& out_default);

struct RegisteredTypeface {
    std::string       family;
    sk_sp<SkTypeface> typeface;
};

std::vector<RegisteredTypeface> registered_typefaces_snapshot();

std::vector<RegisteredTypeface> bundled_typefaces_snapshot();

bool platform_font_db_usable();

sk_sp<SkTypeface> bundled_fallback_typeface();

std::size_t bundled_font_count();

struct FontProbe {
    std::string family;            
    std::uint32_t codepoint = 0;   
    bool family_resolved = false;  
    bool glyph_present = false;    
    std::string resolved_family;   
};
 
FontProbe probe_font_glyph(const std::string& family,
                           int weight, int slant,
                           std::uint32_t codepoint);
 
#endif // PULP_HAS_SKIA
 
} // namespace pulp::canvas