TTFText Component and System
============================

The **TTFText** component provides a mechanism for rendering text using TrueType Fonts (TTF) within the ECS (Entity-Component-System) framework. It stores text content, font path, scale, color, and wrapping options. The **TTFTextSystem** handles the rendering of these text elements by leveraging FreeType to load fonts and generate glyph textures.

Main implementation files:
`ttftext.h <https://github.com/Gallasko/ColumbaEngine/tree/main/src/Engine/2D/ttftext.h>`_,
`ttftext.cpp <https://github.com/Gallasko/ColumbaEngine/tree/main/src/Engine/2D/ttftext.cpp>`_

TTFText Component
-----------------

Attributes
-----------------

- *std::string* ``text``:
    The text content to be rendered.

- *std::string* ``fontPath``:
    The file path to the TrueType Font used for rendering.

- *float* ``scale``:
    The scale factor applied to the rendered text.

- *constant::Vector4D* ``colors``:
    The RGBA color values for the text.

- *bool* ``wrap``:
    Indicates whether text wrapping is enabled.

- *float* ``textWidth``:
    The computed width of the rendered text.

- *float* ``textHeight``:
    The computed height of the rendered text.

- *EntitySystem* ``ecsRef``:
    Reference to the ECS world.

- *\_unique_id* ``entityId``:
    The unique identifier for the entity to which the component is attached.

- *bool* ``changed``:
    A flag indicating whether the text has changed and requires an update.

Methods
-----------------

.. warning::
    All those methods will send a ``EntityChangedEvent`` with the id of the entity holding the ttf component, **if and only if** the underlying value is modified !

- ``setText(const std::string &text)``
    Sets the text content.

- ``setColor(const constant::Vector4D &colors)``
    Sets the text color.

- ``setWrap(bool wrap)``
    Enables or disables text wrapping.

TTFTextCall
-----------

The **TTFTextCall** structure holds a list of render calls generated by the **TTFTextSystem** for a text component. These render calls contain all the necessary data for drawing each glyph.

TTFTextSystem
-------------

The **TTFTextSystem** is responsible for rendering text elements in the UI. It uses FreeType to load fonts and generate textures for individual glyphs, and then creates render calls to display the text on screen.

**Key functionalities:**

- **Initialization:**
    In the ``init()`` method, the system sets up its shader and material preset, and registers a group of entities containing both a **TTFText** component and a **PositionComponent**.

- **Font Registration:**
    The ``registerFont(const std::string &fontPath, int size)`` method loads a font using FreeType, sets pixel sizes, and registers glyph textures for ASCII characters (0-127).

- **Event Handling:**
    The system listens for ``EntityChangedEvent`` events to update text rendering when a **TTFText** component changes.

- **Render Call Creation:**
    Based on whether text wrapping is enabled, the system calls either ``createNormalRenderCall()`` or ``createWrappedRenderCall()`` to generate a list of render calls for each character in the text.

- **Helper Functions:**
    Functions such as ``computeLineHeight()``, ``getGlyphAdvance()``, and ``createGlyphRenderCall()`` calculate font metrics and create individual render calls for glyphs.

Basic Usage Example
-------------------

.. code-block:: cpp

    // Reference to an entity system or a scene !
    EntitySystem *ecsRef;

    // Create a TTFText component with initial text "Hello, World!"
    auto textComponent = makeTTFText(ecsRef, 10, 20, 0,
                                     "res/font/Inter/static/Inter_28pt-Light.ttf",
                                     "Hello, World!",
                                     1.0f,
                                     {255.0f, 255.0f, 255.0f, 255.0f});

    // Update the text content dynamically
    textComponent.get<TTFText>()->setText("New Text Content");

    // Optionally, change the text color
    textComponent.get<TTFText>()->setColor({0.0f, 128.0f, 255.0f, 255.0f});

    // The TTFTextSystem will process the update and generate render calls
    // to display the text on screen.

In this example:
    - A **TTFText** component is created using ``makeTTFText``, specifying position, font, text, scale, and color.
    - The text content is updated using the **setText** method.
    - The text color is changed via **setColor**.
    - The **TTFTextSystem** automatically processes these updates to generate the necessary render calls.

Conclusion
----------

The **TTFText** component and **TTFTextSystem** together provide a robust framework for rendering text within the ECS. By storing text properties and using FreeType to generate glyph textures, the system supports dynamic text rendering with customizable fonts, scales, colors, and wrapping options.

For further details, please refer to the source files:
`ttftext.h <https://github.com/Gallasko/ColumbaEngine/tree/main/src/Engine/2D/ttftext.h>`_ and `ttftext.cpp <https://github.com/Gallasko/ColumbaEngine/tree/main/src/Engine/2D/ttftext.cpp>`_.