font_scope.hpp

Go to the documentation of this file.

// font_scope.hpp
//
// A `FontScope` is a named owner of font registrations. Three built-in
// scopes exist:
//
//   * `Scope::Global` — what `register_font()` writes today; behaves
//     identically for back-compat.
//   * `Scope::Plugin(id)` — per-plugin registrations. Two plugins loaded
//     into the same host see *only* their own registrations plus the
//     Global scope; they cannot pollute each other's resolution.
//   * `Scope::View(id)` — per-view overrides. Used by design-import hot
//     reload and by `pulp-ui-preview --font` flags.
//
// Resolution (in `FontResolver::resolve_*`) walks scopes in this order:
//
//     View → Plugin → Global → Bundled → Platform
//
// Each scope tracks its own monotonic generation counter; the resolver
// merges them (`merged_generation_for(FontScopeId)`) into the
// `registry_generation` field of `FontOptions` so every downstream cache
// key is correctly invalidated when *any* applicable scope mutates.
//
// A generation bump in Plugin(A) must not dirty measure callbacks
// belonging to Plugin(B). This is enforced by `merged_generation_for`
// returning a value that only changes when scopes the caller actually
// consults change.
 
#pragma once
 
#include "pulp/canvas/font_options.hpp"
 
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <string>
 
namespace pulp::canvas {
 
class FontScope {
public:
    explicit FontScope(FontScopeId id);
    ~FontScope();
 
    FontScope(const FontScope&) = delete;
    FontScope& operator=(const FontScope&) = delete;
 
    FontScopeId id() const noexcept { return id_; }

    std::uint64_t generation() const noexcept;

    void bump_generation();

    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 = "");

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

    void set_memory_budget(std::size_t bytes);
    std::size_t memory_budget() const noexcept;

    void prune_to_budget();
 
private:
    FontScopeId id_;
    std::atomic<std::uint64_t> generation_{0};
    std::atomic<std::size_t> memory_budget_{0};
 
    struct Impl;
    std::unique_ptr<Impl> impl_;
};
 
// ── Built-in scope accessors ─────────────────────────────────────────────

FontScope& global_scope();

FontScope& plugin_scope(std::uint64_t plugin_id);

FontScope& view_scope(std::uint64_t view_id);

void release_view_scope(std::uint64_t view_id);
 
// ── Generation merging ───────────────────────────────────────────────────

std::uint64_t merged_generation_for(FontScopeId requesting_scope);
 
} // namespace pulp::canvas