Class FontService

Class Documentation

class FontService

Declaration: final

CPU font catalogue owned by an Engine context or used independently.

Configure before creating consumers. Configuration publishes one complete snapshot; existing Font handles stay valid and consumers are not rebound. Catalogue calls are synchronized; caller-supplied RNGs remain caller-owned. Missing/unloadable families are unavailable. No source replacement checking or file access happens during lookup or rendering.

Public Functions

FontService()

Create a synchronized catalogue service.

Its embedded default is initialized lazily when queried; no provider or graphics context is required.

~FontService()

Release catalogue ownership after callers have stopped using the service.

Retained Font snapshots remain valid.

FontService(const FontService&) = delete
FontService &operator=(const FontService&) = delete
void configure(const FontConfiguration &configuration)

Build then publish a complete catalogue snapshot.

Existing handles and toolkit consumers are unchanged. Invalid/reserved/duplicate identifiers reject configuration; unavailable families are omitted. Discovery/loading/allocation failures can propagate; failure before publication preserves the previous catalogue.

See also

Configure fonts

Parameters:

configuration – Family, group, default and common fallback policy borrowed for this call.

void configure(const FontSelection &selection)

Load an ordered collection under the reference application-default.

Selected bytes are retained for adapters without reopening their paths. Loading failure preserves the preceding catalogue.

See also

configure(const FontSelection&, std::string)

void configure(const FontSelection &selection, std::string reference)

Publish an ordered default/fallback collection under an application reference.

The nonempty reference cannot contain NUL or collide with cheryl:embedded/generated source references. Selected sources are separately named by retained UTF-8 path and collection index; their identities do not depend on preference positions. Loading/validation/allocation failures propagate before publication.

Parameters:

  • selection – CPU loading/discovery policy, borrowed for this call.

  • reference – Owned default identity, copied into the retained snapshot.

Font default_font() const

Declaration: [[nodiscard]]

Return a retained configured default, or embedded DejaVu Sans before configuration/when the requested default is unavailable.

The result survives service destruction.

Font get(std::string_view reference) const

Declaration: [[nodiscard]]

Look up an exact case-sensitive application reference.

Unknown/unavailable references return default_font(), not an empty handle. No file access occurs during lookup; lazy initialization/allocation may throw.

std::vector<Font> all() const

Declaration: [[nodiscard]]

Return owned handles for available named choices plus embedded, ordered lexically by reference.

This catalogue list is not a random-choice group or implicit fallback policy; allocation failures propagate.

std::vector<Font> fallbacks() const

Declaration: [[nodiscard]]

Return the ordered common glyph fallback handles, ending in embedded.

Import each handle’s primary family; specialty catalogue entries are not automatically fallbacks. Ordered FontSelection fallback-only sources retain path/index identities.

Font choose_random(std::string_view group)

Declaration: [[nodiscard]]

Choose uniformly among available distinct members of the named group using the service-owned generator.

Missing/empty/unavailable groups use the default. Persist the returned reference() to keep a choice; entropy/allocation failures can propagate.

See also

Choose and save a font

Font choose_random(std::string_view group, std::mt19937_64 &random) const

Declaration: [[nodiscard]]

Choose as choose_random(group) using the caller’s generator, whose state advances only when a random choice is needed.

The caller synchronizes other access to that generator; service synchronization does not protect external RNG users.

Font restore_or_choose(std::string_view group, std::string_view saved_reference)

Declaration: [[nodiscard]]

Retain a saved choice only while available and still a member of this group; otherwise select a replacement using the service generator.

Unknown/empty groups use default. Save the returned reference, including a replacement, for later runs. No font-byte serialization or source-replacement detection occurs.

Font restore_or_choose(std::string_view group, std::string_view saved_reference, std::mt19937_64 &random) const

Declaration: [[nodiscard]]

Restore or replace as the two-argument overload using a caller-owned RNG.

A valid saved member or default fallback does not draw randomly. External access to random requires caller synchronization.