YiTextEngine.h

Go to the documentation of this file.

// © You i Labs Inc. All rights reserved.
#ifndef _YI_TEXT_ENGINE_H_
#define _YI_TEXT_ENGINE_H_

#include "graphics/YiRectangle.h"
#include "utility/YiColor.h"
#include "utility/YiEnumBitmaskOperators.h"
#include "utility/YiString.h"

#include <glm/gtc/type_ptr.hpp>

#include <functional>
#include <map>
#include <unordered_map>

class CYIAbstractTextAtlas;
class CYIBitmap;
class CYIGenericFontRegistry;
class CYIRuntimeTypeInfo;
class CYISDFTextAtlas;
class CYITextAtlas;
class CYITextLayout;
class CYITextRenderer;
class CYITextSceneNode;
struct YI_GLYPH_DETAILS;

class CYITextEngine
{
public:
    enum class Flags
    {
        None = 0x00,
        Left = 0x01,
        Center = 0x02,
        Right = 0x04,
        Ellipses = 0x08,
        Multiline = 0x10,
        UserWidth = 0x20,
        FontTables = 0x40,
        CacheGlyphBitmapOnFirstRequest = 0x80,
        CacheGlyphBitmapAlways = 0x100,
        DefaultTrimming = 0x200
    };

    enum class TextType
    {
        Atlas = 0, 
        SDFAtlas, 
        All 
    };

    enum class GlyphsBitmapPrefetchMode : uint8_t
    {
        NoPrefetch, 
        Bitmap, 
        SDF 
    };

    enum class ScriptMode
    {
        Regular = 0,
        Subscript,
        Superscript
    };

    enum class FontStyle
    {
        Regular = 0,
        Bold,
        BoldItalic,
        Italic
    };

    enum class LineStyle
    {
        None = 0,
        Underline
    };

    struct TextHeight
    {
        float heightAboveBase;
        float heightBelowBase;
        float trueBaseOffset;
        float lowercaseLHeightAboveBase;

        bool operator<(TextHeight const &other) const;
        bool operator==(TextHeight const &other) const;
    };

    struct FontInfo
    {
        ssize_t engineID;
        CYIString filename;
        CYIString name;
        CYIString family;
        CYIString style;
    };

    class PositionInString
    {
    public:
        PositionInString();

        /*
            \details Sets the string position before the character with index \a logicalPosition, or at the end of the text if \a logicalPosition is equal to the number of characters. Alignment with the previous character is automatically determined.

            \note Use this function to set the position if it doesn't matter where the caret appears visually, as long as it appears in a valid visual position corresponding to the logical position. Otherwise use #SetPosition.
        */
        void SetBasicPosition(size_t logicalPosition);

        /*
            \details Sets the string position before the character with index \a logicalPosition, or at the end of the text if \a logicalPosition is equal to the number of characters. The position is aligned with the edge of the character at \a logicalPosition if \a alignWithPreviousCharacter is false, and with the character immediately before, if it's true.

            \note If \a logicalPosition is 0, \a alignWithPreviousCharacter cannot be true, and if \a logicalPosition is equal to the number of characters, \a alignWithPreviousCharacter must be true.

            \note Use this function to set the position if it's important which of the two characters the position is logically adjacent to, that the caret should visually align with, such as in bidirectional text where two logically adjacent characters may not be visually adjacent. Otherwise use #SetBasicPosition.
        */
        void SetPosition(size_t logicalPosition, bool alignWithPreviousCharacter);

        /*
            \details Returns true if the string position represents alignment with an edge of the previous character. Returns false otherwise.
        */
        bool IsAlignedWithPreviousCharacter() const;

        /*
            \details Returns the index of the space between two characters in the text that this position represents, where 0 is before the first character, and the number of characters is after the last character.
        */
        size_t GetLogicalPosition() const;

        /*
            \details Sets the position to represent the absolute start of the string, logically positioned before the first character, but visually positioned on the left or right edge of the string depending on the text direction.
        */
        void SetIsAbsoluteStart();

        /*
            \details Sets the position to represent the absolute end of the string, logically positioned after the first character, but visually positioned on the right or left edge of the string depending on the text direction.
        */
        void SetIsAbsoluteEnd(size_t characterCount);

        /*
            \details Returns true if the position is set to the absolute start of the string. Returns false otherwise.
        */
        bool IsAbsoluteStart() const;

        /*
            \details Returns true if the position is set to the absolute end of the string. Returns false otherwise.
        */
        bool IsAbsoluteEnd() const;

        bool operator==(const CYITextEngine::PositionInString &rhs) const;

    private:
        size_t m_logicalPosition;
        bool m_alignWithPreviousCharacter;
        bool m_isAbsoluteStart;
        bool m_isAbsoluteEnd;
    };

    enum class TrimmingMode
    {
        Default = 0, /*< Default trimming behavior. If the text alignment is the start alignement for the text direction (i.e. left-aligned left-to-right text, or right-aligned right-to-left text), then the start of the string will be trimmed for all lines but the first line of each paragraph, and the end of the line will always be trimmed. Otherwise, the start and the end of all lines will always be trimmed. */
        None = 1 /*< No whitespace trimming is done on any lines of text */
    };

    struct TextStyle
    {
        TextStyle();

        ssize_t fontID;
        float fontSize;
        float unadjustedFontSize;
        float leading;
        ScriptMode scriptMode;
        float baselineShift;
        float tracking;
        float kerning;
        CYIColor Color;
        LineStyle textLineStyle;

        size_t lastCodepointIndex;

        bool operator<(TextStyle const &other) const;
        bool operator==(TextStyle const &other) const;
    };

    struct RenderInfo
    {
        RenderInfo();
        RenderInfo(Flags flags, float offsetX, float yScale, const YI_FLOAT_RECT &rect, int32_t numberOfLines, bool adjustsFontSizeToFit, float minimumFontScale, const CYIString &text, const std::vector<TextStyle> &styles, float fontSizeForCachingGlyphBitmap = -1, GlyphsBitmapPrefetchMode prefetchMode = GlyphsBitmapPrefetchMode::NoPrefetch);

        /*
        If you update this structure, make sure to update the comparison operators.
        */
        Flags flags;
        float offsetX;
        float yScale;
        YI_FLOAT_RECT rect;
        int32_t numberOfLines;
        bool adjustsFontSizeToFit;
        float minimumFontScale;
        CYIString text;

        float fontSizeForCachingGlyphBitmap;
        GlyphsBitmapPrefetchMode prefetchMode;

        std::vector<TextStyle> styles;

        /* Comparator used by the \a std::map. */
        bool operator<(RenderInfo const &other) const;

        /*
        This function should be kept up to date with any field that would cause
        a relayout.
        */
        bool operator==(const RenderInfo &other) const;
        bool operator!=(const RenderInfo &other) const;
    };

    struct RenderResult
    {
        RenderResult();
        operator bool() const;

        bool succeeded;
        uint32_t renderedGlyphsCount;
    };

    static const size_t s_textEllipsisCodepointIndex;

    static const float s_lineSpacingFactor;

    CYITextEngine();
    virtual ~CYITextEngine();

    bool Init(uint16_t maxFonts, const std::map<CYITextEngine::TextType, uint16_t> &textAtlasSizes);

    bool IsInitialized() const;

    ssize_t GetFontId(const CYIString &fontName) const;

    ssize_t GetFontId(const CYIString &fontFamilyName, const CYIString &fontStyleName, bool ignoreCase = false) const;

    ssize_t GetFontIdFromNameAndStyle(const CYIString &fontName, const CYIString &fontStyleName, bool ignoreCase = false) const;

    const FontInfo &GetFontInfo(ssize_t fontID) const;

    std::vector<CYIString> GetFontStyles(ssize_t fontID) const;

    std::vector<CYIString> GetFontStyles(const CYIString &fontFamilyName) const;

    std::vector<CYIString> ReadFontStyles(const CYIString &url) const;

    std::vector<CYIString> ReadFontStyles(const uint8_t *pFontData, uint32_t dataSize) const;

    ssize_t AddFont(const CYIString &url);

    ssize_t AddFont(const CYIString &url, const CYIString &fontName);

    ssize_t AddFont(const CYIString &url, const CYIString &fontName, const CYIString &fontStyle);

    ssize_t AddFontWithOverrides(const CYIString &url, const CYIString &fontName, const CYIString &fontFamily, const CYIString &fontStyle);

    ssize_t AddFont(const uint8_t *pFontData, size_t dataSize);

    ssize_t AddFont(const uint8_t *pFontData, size_t dataSize, const CYIString &fontName, const CYIString &fontStyle);

    bool IsFontInFile(const CYIString &familyName, const CYIString &styleName, const CYIString &url) const;

    uint32_t GetNumFonts() const;

    bool AddPregeneratedTextData(const CYIString &path);

    bool AddPregeneratedTextData(const uint8_t *pPregeneratedTextData, size_t dataSize);

    TextHeight GetTextHeight(ssize_t fontID, float fontSize) const;

    RenderResult RenderText(const CYITextLayout *pTextLayout,
                            CYIBitmap *pDestination,
                            const RenderInfo &textRenderInfo,
                            const glm::vec2 &renderOffset,
                            const YI_FLOAT_RECT *pTextExtents = nullptr);

    int32_t RenderGlyphIntoAtlas(YI_GLYPH_DETAILS *pGlyph, CYIAbstractTextAtlas *pAtlas);

    size_t GetCharacterIndex(ssize_t fontID, uint32_t character) const;

    CYITextEngine::PositionInString GetIndexOfPosition(const CYITextLayout *pTextLayout, float x, float y, float horizontalPixelRatio, float verticalPixelRatio) const;

    YI_FLOAT_RECT GetRectForTextRange(const CYITextLayout *pTextLayout, size_t startIndex, size_t endIndex, float horizontalPixelRatio, float verticalPixelRatio) const;

    CYITextAtlas *GetTextAtlas() const;

    CYISDFTextAtlas *GetSDFTextAtlas() const;

    bool SetTextAtlas(std::unique_ptr<CYITextAtlas> pAtlas);

    bool SetSDFTextAtlas(std::unique_ptr<CYISDFTextAtlas> pAtlas);

    CYITextRenderer *GetTextRenderer() const;

    uint16_t GetTextAtlasSize(CYITextEngine::TextType textAtlasType = CYITextEngine::TextType::All) const;

    std::unique_ptr<CYITextLayout> GetTextLayout(const RenderInfo &textInfo, const std::function<std::unique_ptr<CYITextLayout>()> &textLayoutFactory = nullptr) const;

    ssize_t FindFontByFamilyName(const CYIString &fontFamilyName, FontStyle fontStyle = FontStyle::Regular) const;

    void SetDefaultTextNodeType(const CYIRuntimeTypeInfo &nodeType);
    const CYIRuntimeTypeInfo &GetDefaultTextNodeType() const;

    std::unique_ptr<CYITextSceneNode> CreateTextSceneNode() const;

private:
    std::unique_ptr<CYITextLayout> CreateTextLayout() const;

    void AddFontPriv(ssize_t fontID, const CYIString &filename, const CYIString &fontName, const CYIString &fontFamilyName, const CYIString &fontStyleName);

    std::vector<FontInfo> m_fontsInfo;

    std::unique_ptr<CYITextRenderer> m_pTextRenderer;

    std::unique_ptr<CYITextAtlas> m_pTextAtlas;
    std::unique_ptr<CYISDFTextAtlas> m_pSDFTextAtlas;

    // Stores the size of each text atlas in pixels.
    std::vector<uint16_t> m_textAtlasSizes;

    mutable std::unordered_map<CYIString, ssize_t> m_fontFamilyCache;

    std::unique_ptr<CYIGenericFontRegistry> m_pGenericFontRegistry;

    const CYIRuntimeTypeInfo *m_pDefaultTextNodeType;

    YI_DISALLOW_COPY_AND_ASSIGN(CYITextEngine)
};

template<>
struct YiEnableBitmaskOperators<CYITextEngine::Flags>
{
    static const bool enable = true;
};

#endif // _YI_TEXT_ENGINE_H_