.. index:: pair: class; EE::Graphics::FontService
.. _doxid-class_e_e_1_1_graphics_1_1_font_service:

class EE::Graphics::FontService
===============================

.. toctree::
	:hidden:

Overview
~~~~~~~~

Owns font fallback state and rendering policy for a :ref:`ResourceScope <doxid-class_e_e_1_1_graphics_1_1_resource_scope>`. :ref:`More...<details-class_e_e_1_1_graphics_1_1_font_service>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	#include <fontservice.hpp>
	
	class FontService {
	public:
		// construction
	
		:ref:`FontService<doxid-class_e_e_1_1_graphics_1_1_font_service_1a388bbcd053316745a5dabe0f162c1519>`(:ref:`ResourceScope<doxid-class_e_e_1_1_graphics_1_1_resource_scope>`& resourceScope);

		// methods
	
		:ref:`ResourceScope<doxid-class_e_e_1_1_graphics_1_1_resource_scope>`& :ref:`getResourceScope<doxid-class_e_e_1_1_graphics_1_1_font_service_1a983aca8b74e3d5a894af8ada13a54b81>`() const;
		:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_font>`* :ref:`getColorEmojiFont<doxid-class_e_e_1_1_graphics_1_1_font_service_1ae33883f697f20d2c99be75054738baf8>`() const;
		void :ref:`setColorEmojiFont<doxid-class_e_e_1_1_graphics_1_1_font_service_1ad0759b6cbd7822974628069b50bf2909>`(:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_font>`* font);
		:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_font>`* :ref:`getEmojiFont<doxid-class_e_e_1_1_graphics_1_1_font_service_1a70d618b3f4b9662c16e8e23bba48ea64>`() const;
		void :ref:`setEmojiFont<doxid-class_e_e_1_1_graphics_1_1_font_service_1a859071bf18cb7b9ff8153adb00dc3cfd>`(:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_font>`* font);
		const std::vector<:ref:`FontPtr<doxid-namespace_e_e_1_1_graphics_1a204d963a20d37023d8db99da16b2f4f5>`>& :ref:`getFallbackFonts<doxid-class_e_e_1_1_graphics_1_1_font_service_1ae5f6a9356e12e4461922ff6184854b6b>`() const;
		bool :ref:`hasFallbackFonts<doxid-class_e_e_1_1_graphics_1_1_font_service_1a5ca245e301413fbab26ddb2f30bc7e23>`() const;
		bool :ref:`addFallbackFont<doxid-class_e_e_1_1_graphics_1_1_font_service_1a9e5d1e35a4a83412359fb662855641ca>`(:ref:`FontPtr<doxid-namespace_e_e_1_1_graphics_1a204d963a20d37023d8db99da16b2f4f5>` fallbackFont);
		bool :ref:`addFallbackFont<doxid-class_e_e_1_1_graphics_1_1_font_service_1a7fef930ca6a0fdabb15f83cae6da9150>`(:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_font>`* fallbackFont);
		bool :ref:`removeFallbackFont<doxid-class_e_e_1_1_graphics_1_1_font_service_1a6a24f8f43469ac0df81abc0b8e88b00f>`(:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_font>`* fallbackFont);
		:ref:`FontHinting<doxid-namespace_e_e_1_1_graphics_1ad2a705ec167b94a204a11b4240b1743d>` :ref:`getHinting<doxid-class_e_e_1_1_graphics_1_1_font_service_1a62dfc42b42868dcd703ddfca81a609c2>`() const;
		void :ref:`setHinting<doxid-class_e_e_1_1_graphics_1_1_font_service_1a038d04dbe611c6265d30f20eaec29086>`(:ref:`FontHinting<doxid-namespace_e_e_1_1_graphics_1ad2a705ec167b94a204a11b4240b1743d>` hinting);
		:ref:`FontAntialiasing<doxid-namespace_e_e_1_1_graphics_1aa057d5e42433ff4e64addb85338a9920>` :ref:`getAntialiasing<doxid-class_e_e_1_1_graphics_1_1_font_service_1a59787fef782da0c376a297b1d5b71924>`() const;
		void :ref:`setAntialiasing<doxid-class_e_e_1_1_graphics_1_1_font_service_1a82f9490e1371d0deab002e632d5fd668>`(:ref:`FontAntialiasing<doxid-namespace_e_e_1_1_graphics_1aa057d5e42433ff4e64addb85338a9920>` antialiasing);
		:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_font>`* :ref:`getByInternalId<doxid-class_e_e_1_1_graphics_1_1_font_service_1a35270c227e85610ede40d53191892c44>`(:ref:`Uint32<doxid-namespace_e_e_1acb11e434631749f2da0e0004d6038558>` internalId) const;
		:ref:`ResourcePtr<doxid-namespace_e_e_1_1_graphics_1a3a04fbd436755a3a13bf6a370a3b3d75>`<:ref:`FontTrueType<doxid-class_e_e_1_1_graphics_1_1_font_true_type>`> :ref:`loadSystemFont<doxid-class_e_e_1_1_graphics_1_1_font_service_1a63464f911f03c33215033cb9d3de875b>`(const :ref:`FontDesc<doxid-struct_e_e_1_1_graphics_1_1_font_desc>`& desc);
		:ref:`FontTrueType<doxid-class_e_e_1_1_graphics_1_1_font_true_type>`* :ref:`getOrLoadSystemFallbackFont<doxid-class_e_e_1_1_graphics_1_1_font_service_1a75b6d6a1ddd28095e757d2743983db4f>`(const :ref:`FontDesc<doxid-struct_e_e_1_1_graphics_1_1_font_desc>`& desc);
	};
.. _details-class_e_e_1_1_graphics_1_1_font_service:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

Owns font fallback state and rendering policy for a :ref:`ResourceScope <doxid-class_e_e_1_1_graphics_1_1_resource_scope>`.

Every :ref:`ResourceScope <doxid-class_e_e_1_1_graphics_1_1_resource_scope>` has one :ref:`FontService <doxid-class_e_e_1_1_graphics_1_1_font_service>`. 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 :ref:`FontTrueType <doxid-class_e_e_1_1_graphics_1_1_font_true_type>` stores one borrowed :ref:`FontService <doxid-class_e_e_1_1_graphics_1_1_font_service>` pointer, so the same :ref:`FontTrueType <doxid-class_e_e_1_1_graphics_1_1_font_true_type>` 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.

:ref:`System <doxid-namespace_e_e_1_1_system>` fonts can be loaded with two different lifetime contracts:

* :ref:`loadSystemFont() <doxid-class_e_e_1_1_graphics_1_1_font_service_1a63464f911f03c33215033cb9d3de875b>` returns an independently owned, uncached font.

* :ref:`getOrLoadSystemFallbackFont() <doxid-class_e_e_1_1_graphics_1_1_font_service_1a75b6d6a1ddd28095e757d2743983db4f>` retains the font in this service for repeated fallback lookup.

Construction
------------

.. index:: pair: function; FontService
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a388bbcd053316745a5dabe0f162c1519:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	FontService(:ref:`ResourceScope<doxid-class_e_e_1_1_graphics_1_1_resource_scope>`& resourceScope)

Creates a service associated with ``resourceScope``. :ref:`ResourceScope <doxid-class_e_e_1_1_graphics_1_1_resource_scope>` owns its service.

Methods
-------

.. index:: pair: function; getResourceScope
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a983aca8b74e3d5a894af8ada13a54b81:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`ResourceScope<doxid-class_e_e_1_1_graphics_1_1_resource_scope>`& getResourceScope() const



.. rubric:: Returns:

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

.. index:: pair: function; getColorEmojiFont
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1ae33883f697f20d2c99be75054738baf8:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_font>`* getColorEmojiFont() const



.. rubric:: Returns:

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

.. index:: pair: function; setColorEmojiFont
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1ad0759b6cbd7822974628069b50bf2909:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void setColorEmojiFont(:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_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.

.. index:: pair: function; getEmojiFont
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a70d618b3f4b9662c16e8e23bba48ea64:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_font>`* getEmojiFont() const



.. rubric:: Returns:

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

.. index:: pair: function; setEmojiFont
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a859071bf18cb7b9ff8153adb00dc3cfd:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void setEmojiFont(:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_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.

.. index:: pair: function; getFallbackFonts
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1ae5f6a9356e12e4461922ff6184854b6b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	const std::vector<:ref:`FontPtr<doxid-namespace_e_e_1_1_graphics_1a204d963a20d37023d8db99da16b2f4f5>`>& getFallbackFonts() const



.. rubric:: Returns:

The strongly owned explicit fallback fonts in lookup order.

.. index:: pair: function; hasFallbackFonts
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a5ca245e301413fbab26ddb2f30bc7e23:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool hasFallbackFonts() const



.. rubric:: Returns:

Whether at least one explicit fallback font is configured.

.. index:: pair: function; addFallbackFont
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a9e5d1e35a4a83412359fb662855641ca:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool addFallbackFont(:ref:`FontPtr<doxid-namespace_e_e_1_1_graphics_1a204d963a20d37023d8db99da16b2f4f5>` fallbackFont)

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

.. index:: pair: function; addFallbackFont
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a7fef930ca6a0fdabb15f83cae6da9150:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool addFallbackFont(:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_font>`* fallbackFont)

Adds a fallback font resolved through the associated scope.



.. rubric:: Returns:

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

.. index:: pair: function; removeFallbackFont
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a6a24f8f43469ac0df81abc0b8e88b00f:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool removeFallbackFont(:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_font>`* fallbackFont)

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

.. index:: pair: function; getHinting
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a62dfc42b42868dcd703ddfca81a609c2:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`FontHinting<doxid-namespace_e_e_1_1_graphics_1ad2a705ec167b94a204a11b4240b1743d>` getHinting() const



.. rubric:: Returns:

The policy used when loading and updating associated TrueType fonts.

.. index:: pair: function; setHinting
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a038d04dbe611c6265d30f20eaec29086:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void setHinting(:ref:`FontHinting<doxid-namespace_e_e_1_1_graphics_1ad2a705ec167b94a204a11b4240b1743d>` hinting)

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

.. index:: pair: function; getAntialiasing
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a59787fef782da0c376a297b1d5b71924:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`FontAntialiasing<doxid-namespace_e_e_1_1_graphics_1aa057d5e42433ff4e64addb85338a9920>` getAntialiasing() const



.. rubric:: Returns:

The antialiasing policy used by associated TrueType fonts.

.. index:: pair: function; setAntialiasing
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a82f9490e1371d0deab002e632d5fd668:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void setAntialiasing(:ref:`FontAntialiasing<doxid-namespace_e_e_1_1_graphics_1aa057d5e42433ff4e64addb85338a9920>` antialiasing)

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

.. index:: pair: function; getByInternalId
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a35270c227e85610ede40d53191892c44:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`Font<doxid-class_e_e_1_1_graphics_1_1_font>`* getByInternalId(:ref:`Uint32<doxid-namespace_e_e_1acb11e434631749f2da0e0004d6038558>` internalId) const

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



.. rubric:: Returns:

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

.. index:: pair: function; loadSystemFont
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a63464f911f03c33215033cb9d3de875b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`ResourcePtr<doxid-namespace_e_e_1_1_graphics_1a3a04fbd436755a3a13bf6a370a3b3d75>`<:ref:`FontTrueType<doxid-class_e_e_1_1_graphics_1_1_font_true_type>`> loadSystemFont(const :ref:`FontDesc<doxid-struct_e_e_1_1_graphics_1_1_font_desc>`& 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.



.. rubric:: Returns:

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

.. index:: pair: function; getOrLoadSystemFallbackFont
.. _doxid-class_e_e_1_1_graphics_1_1_font_service_1a75b6d6a1ddd28095e757d2743983db4f:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`FontTrueType<doxid-class_e_e_1_1_graphics_1_1_font_true_type>`* getOrLoadSystemFallbackFont(const :ref:`FontDesc<doxid-struct_e_e_1_1_graphics_1_1_font_desc>`& 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.



.. rubric:: Returns:

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