class EE::Graphics::FontService

Overview

Owns font fallback state and rendering policy for a ResourceScope. More…

#include <fontservice.hpp>

class FontService {
public:
    // construction

    FontService(ResourceScope& resourceScope);

    // methods

    ResourceScope& getResourceScope() const;
    Font* getColorEmojiFont() const;
    void setColorEmojiFont(Font* font);
    Font* getEmojiFont() const;
    void setEmojiFont(Font* font);
    const std::vector<FontPtr>& getFallbackFonts() const;
    bool hasFallbackFonts() const;
    bool addFallbackFont(FontPtr fallbackFont);
    bool addFallbackFont(Font* fallbackFont);
    bool removeFallbackFont(Font* fallbackFont);
    FontHinting getHinting() const;
    void setHinting(FontHinting hinting);
    FontAntialiasing getAntialiasing() const;
    void setAntialiasing(FontAntialiasing antialiasing);
    Font* getByInternalId(Uint32 internalId) const;
    ResourcePtr<FontTrueType> loadSystemFont(const FontDesc& desc);
    FontTrueType* getOrLoadSystemFallbackFont(const FontDesc& desc);
};

Detailed Documentation

Owns font fallback state and rendering policy for a ResourceScope.

Every ResourceScope has one FontService. Fonts published locally by that scope are associated with its service, allowing glyph lookup to resolve configured emoji, explicit fallback, and system fallback fonts without consulting global state.

The service strongly owns configured emoji and fallback fonts. Raw-pointer setters only accept fonts that can be resolved through the associated scope; passing an unrelated pointer clears or ignores the corresponding configuration. Removing a locally published font from the scope also removes any service references to it.

Rendering policy changes are applied to TrueType fonts associated with this service. Imported fonts remain associated with the service of their owning scope and are therefore not mutated. A FontTrueType stores one borrowed FontService pointer, so the same FontTrueType instance must not be published locally into multiple scopes: the latest publication would replace its service association. Share such a font by importing its owning catalog instead. A future design may move fallback resolution entirely out of the shared font object and remove this restriction.

System fonts can be loaded with two different lifetime contracts:

Construction

FontService(ResourceScope& resourceScope)

Creates a service associated with resourceScope. ResourceScope owns its service.

Methods

ResourceScope& getResourceScope() const

Returns:

The resource scope whose fonts and policy are managed by this service.

Font* getColorEmojiFont() const

Returns:

The configured color emoji font, or nullptr when none is configured.

void setColorEmojiFont(Font* font)

Sets the color emoji font. The font must be resolvable through the associated scope. Passing nullptr or an unrelated font clears the current value.

Font* getEmojiFont() const

Returns:

The configured monochrome emoji font, or nullptr when none is configured.

void setEmojiFont(Font* font)

Sets the monochrome emoji font. The font must be resolvable through the associated scope. Passing nullptr or an unrelated font clears the current value.

const std::vector<FontPtr>& getFallbackFonts() const

Returns:

The strongly owned explicit fallback fonts in lookup order.

bool hasFallbackFonts() const

Returns:

Whether at least one explicit fallback font is configured.

bool addFallbackFont(FontPtr fallbackFont)

Adds an owning fallback handle unless the same font is already configured.

bool addFallbackFont(Font* fallbackFont)

Adds a fallback font resolved through the associated scope.

Returns:

True when the font was found and added; false otherwise.

bool removeFallbackFont(Font* fallbackFont)

Removes the matching explicit fallback font without removing it from its resource scope.

FontHinting getHinting() const

Returns:

The policy used when loading and updating associated TrueType fonts.

void setHinting(FontHinting hinting)

Updates the hinting policy and applies it to associated non-emoji TrueType fonts.

FontAntialiasing getAntialiasing() const

Returns:

The antialiasing policy used by associated TrueType fonts.

void setAntialiasing(FontAntialiasing antialiasing)

Updates the antialiasing policy and applies it to associated non-emoji TrueType fonts.

Font* getByInternalId(Uint32 internalId) const

Finds a TrueType font visible through the associated scope by its runtime internal ID.

Returns:

A borrowed pointer, or nullptr when no matching font is visible.

ResourcePtr<FontTrueType> loadSystemFont(const FontDesc& desc)

Loads a standalone system font described by desc.

The font is not published into the associated scope and is not retained by this service. The returned handle is its sole owner and can be released independently, immediately freeing its glyph pages when no other handle exists. Current hinting and antialiasing policy is applied at load time. The standalone font does not use this service for subsequent fallback resolution.

Returns:

An owning handle, or an empty handle when the descriptor cannot be loaded.

FontTrueType* getOrLoadSystemFallbackFont(const FontDesc& desc)

Finds or loads a system fallback font described by desc.

Successfully loaded fonts are published into the associated scope and strongly retained by the service for future glyph fallback requests. The returned pointer is borrowed and remains valid until the font is removed from the scope or the service is destroyed.

Returns:

A borrowed pointer to the cached font, or nullptr when loading fails.