You.i Engine
YiTextEngine.h
Go to the documentation of this file.
1 // © You i Labs Inc. All rights reserved.
2 #ifndef _YI_TEXT_ENGINE_H_
3 #define _YI_TEXT_ENGINE_H_
4 
5 #include "graphics/YiRectangle.h"
6 #include "utility/YiColor.h"
8 #include "utility/YiString.h"
9 
10 #include <glm/gtc/type_ptr.hpp>
11 
12 #include <functional>
13 #include <map>
14 #include <unordered_map>
15 
17 class CYIBitmap;
18 class CYIGenericFontRegistry;
19 class CYIRuntimeTypeInfo;
20 class CYISDFTextAtlas;
21 class CYITextAtlas;
22 class CYITextLayout;
23 class CYITextRenderer;
24 class CYITextSceneNode;
25 struct YI_GLYPH_DETAILS;
26 
36 {
37 public:
38  enum class Flags
39  {
40  None = 0x00,
41  Left = 0x01,
42  Center = 0x02,
43  Right = 0x04,
44  Ellipses = 0x08,
45  Multiline = 0x10,
46  UserWidth = 0x20,
47  FontTables = 0x40,
49  CacheGlyphBitmapAlways = 0x100,
50  DefaultTrimming = 0x200
51  };
52 
56  enum class TextType
57  {
58  Atlas = 0,
59  SDFAtlas,
60  All
61  };
62 
66  enum class GlyphsBitmapPrefetchMode : uint8_t
67  {
68  NoPrefetch,
69  Bitmap,
70  SDF
71  };
72 
73  enum class ScriptMode
74  {
75  Regular = 0,
76  Subscript,
77  Superscript
78  };
79 
80  enum class FontStyle
81  {
82  Regular = 0,
83  Bold,
84  BoldItalic,
85  Italic
86  };
87 
88  enum class LineStyle
89  {
90  None = 0,
91  Underline
92  };
93 
94  struct TextHeight
95  {
100 
101  bool operator<(TextHeight const &other) const;
102  bool operator==(TextHeight const &other) const;
103  };
104 
105  struct FontInfo
106  {
112  };
113 
118  {
119  public:
121 
122  /*
123  \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.
124 
125  \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.
126  */
127  void SetBasicPosition(size_t logicalPosition);
128 
129  /*
130  \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.
131 
132  \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.
133 
134  \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.
135  */
136  void SetPosition(size_t logicalPosition, bool alignWithPreviousCharacter);
137 
138  /*
139  \details Returns true if the string position represents alignment with an edge of the previous character. Returns false otherwise.
140  */
141  bool IsAlignedWithPreviousCharacter() const;
142 
143  /*
144  \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.
145  */
146  size_t GetLogicalPosition() const;
147 
148  /*
149  \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.
150  */
151  void SetIsAbsoluteStart();
152 
153  /*
154  \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.
155  */
156  void SetIsAbsoluteEnd(size_t characterCount);
157 
158  /*
159  \details Returns true if the position is set to the absolute start of the string. Returns false otherwise.
160  */
161  bool IsAbsoluteStart() const;
162 
163  /*
164  \details Returns true if the position is set to the absolute end of the string. Returns false otherwise.
165  */
166  bool IsAbsoluteEnd() const;
167 
168  bool operator==(const CYITextEngine::PositionInString &rhs) const;
169 
170  private:
171  size_t m_logicalPosition;
172  bool m_alignWithPreviousCharacter;
173  bool m_isAbsoluteStart;
174  bool m_isAbsoluteEnd;
175  };
176 
180  enum class TrimmingMode
181  {
182  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. */
183  None = 1 /*< No whitespace trimming is done on any lines of text */
184  };
185 
186  struct TextStyle
187  {
188  TextStyle();
189 
191  float fontSize;
193  float leading;
196  float tracking;
197  float kerning;
200 
202 
203  bool operator<(TextStyle const &other) const;
204  bool operator==(TextStyle const &other) const;
205  };
206 
210  struct RenderInfo
211  {
212  RenderInfo();
213  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);
214 
215  /*
216  If you update this structure, make sure to update the comparison operators.
217  */
219  float offsetX;
220  float yScale;
222  int32_t numberOfLines;
226 
229 
230  std::vector<TextStyle> styles;
231 
232  /* Comparator used by the \a std::map. */
233  bool operator<(RenderInfo const &other) const;
234 
235  /*
236  This function should be kept up to date with any field that would cause
237  a relayout.
238  */
239  bool operator==(const RenderInfo &other) const;
240  bool operator!=(const RenderInfo &other) const;
241  };
242 
248  {
249  RenderResult();
250  operator bool() const;
251 
252  bool succeeded;
254  };
255 
259  static const size_t s_textEllipsisCodepointIndex;
260 
264  static const float s_lineSpacingFactor;
265 
266  CYITextEngine();
267  virtual ~CYITextEngine();
268 
274  bool Init(uint16_t maxFonts, const std::map<CYITextEngine::TextType, uint16_t> &textAtlasSizes);
275 
279  bool IsInitialized() const;
280 
282  ssize_t GetFontId(const CYIString &fontName) const;
283 
285  ssize_t GetFontId(const CYIString &fontFamilyName, const CYIString &fontStyleName, bool ignoreCase = false) const;
286 
288  ssize_t GetFontIdFromNameAndStyle(const CYIString &fontName, const CYIString &fontStyleName, bool ignoreCase = false) const;
289 
291  const FontInfo &GetFontInfo(ssize_t fontID) const;
292 
294  std::vector<CYIString> GetFontStyles(ssize_t fontID) const;
295 
297  std::vector<CYIString> GetFontStyles(const CYIString &fontFamilyName) const;
298 
300  std::vector<CYIString> ReadFontStyles(const CYIString &url) const;
301 
303  std::vector<CYIString> ReadFontStyles(const uint8_t *pFontData, uint32_t dataSize) const;
304 
306  ssize_t AddFont(const CYIString &URL);
307 
312  ssize_t AddFont(const CYIString &URL, const CYIString &fontName);
313 
315  ssize_t AddFont(const CYIString &URL, const CYIString &fontName, const CYIString &fontStyle);
316 
318  ssize_t AddFontWithOverrides(const CYIString &URL, const CYIString &fontName, const CYIString &fontFamily, const CYIString &fontStyle);
319 
324  ssize_t AddFont(const uint8_t *pFontData, size_t dataSize);
325 
329  ssize_t AddFont(const uint8_t *pFontData, size_t dataSize, const CYIString &fontName, const CYIString &fontStyle);
330 
332  bool IsFontInFile(const CYIString &familyName, const CYIString &styleName, const CYIString &URL) const;
333 
335  uint32_t GetNumFonts() const;
336 
342  bool AddPregeneratedTextData(const CYIString &path);
343 
349  bool AddPregeneratedTextData(const uint8_t *pPregeneratedTextData, size_t dataSize);
350 
352  TextHeight GetTextHeight(ssize_t fontID, float fontSize) const;
353 
355  RenderResult RenderText(const CYITextLayout *pTextLayout,
356  CYIBitmap *pDestination,
357  const RenderInfo &textRenderInfo,
358  const glm::vec2 &renderOffset,
359  const YI_FLOAT_RECT *pTextExtents = nullptr);
360 
370 
374  size_t GetCharacterIndex(ssize_t fontID, uint32_t character) const;
375 
379  CYITextEngine::PositionInString GetIndexOfPosition(const CYITextLayout *pTextLayout, float x, float y, float horizontalPixelRatio, float verticalPixelRatio) const;
380 
384  YI_FLOAT_RECT GetRectForTextRange(const CYITextLayout *pTextLayout, size_t startIndex, size_t endIndex, float horizontalPixelRatio, float verticalPixelRatio) const;
385 
389  CYITextAtlas *GetTextAtlas() const;
390 
395 
399  bool SetTextAtlas(std::unique_ptr<CYITextAtlas> pAtlas);
400 
404  bool SetSDFTextAtlas(std::unique_ptr<CYISDFTextAtlas> pAtlas);
405 
406  CYITextRenderer *GetTextRenderer() const;
407 
415 
419  std::unique_ptr<CYITextLayout> GetTextLayout(const RenderInfo &rTextInfo, const std::function<std::unique_ptr<CYITextLayout>()> &textLayoutFactory = nullptr) const;
420 
424  ssize_t FindFontByFamilyName(const CYIString &fontFamilyName, FontStyle fontStyle = FontStyle::Regular) const;
425 
429  void SetDefaultTextNodeType(const CYIRuntimeTypeInfo &nodeType);
431 
437  std::unique_ptr<CYITextSceneNode> CreateTextSceneNode() const;
438 
439 private:
440  std::unique_ptr<CYITextLayout> CreateTextLayout() const;
441 
442  void AddFontPriv(ssize_t fontID, const CYIString &filename, const CYIString &fontName, const CYIString &fontFamilyName, const CYIString &fontStyleName);
443 
445  std::vector<FontInfo> m_fontsInfo;
446 
447  std::unique_ptr<CYITextRenderer> m_pTextRenderer;
448 
449  std::unique_ptr<CYITextAtlas> m_pTextAtlas;
450  std::unique_ptr<CYISDFTextAtlas> m_pSDFTextAtlas;
451 
452  // Stores the size of each text atlas in pixels.
453  std::vector<uint16_t> m_textAtlasSizes;
454 
456  mutable std::unordered_map<CYIString, ssize_t> m_fontFamilyCache;
457 
458  std::unique_ptr<CYIGenericFontRegistry> m_pGenericFontRegistry;
459 
460  const CYIRuntimeTypeInfo *m_pDefaultTextNodeType;
461 
463 };
464 
467 template<>
469 {
470  static const bool enable = true;
471 };
472 
473 #endif // _YI_TEXT_ENGINE_H_
size_t GetCharacterIndex(ssize_t fontID, uint32_t character) const
uint32_t GetNumFonts() const
CYITextEngine::PositionInString GetIndexOfPosition(const CYITextLayout *pTextLayout, float x, float y, float horizontalPixelRatio, float verticalPixelRatio) const
#define YI_DISALLOW_COPY_AND_ASSIGN(TypeName)
Delete the copy constructor and assignment operator (and consequently the move constructor as well) ...
Definition: YiPredef.h:69
ssize_t FindFontByFamilyName(const CYIString &fontFamilyName, FontStyle fontStyle=FontStyle::Regular) const
Struct used to pass information when rendering text.
Definition: YiTextEngine.h:210
float trueBaseOffset
Definition: YiTextEngine.h:98
Definition: YiTextEngine.h:105
float fontSize
Definition: YiTextEngine.h:191
std::vector< TextStyle > styles
Definition: YiTextEngine.h:230
float tracking
Definition: YiTextEngine.h:196
float lowercaseLHeightAboveBase
Definition: YiTextEngine.h:99
bool SetSDFTextAtlas(std::unique_ptr< CYISDFTextAtlas > pAtlas)
Container class for Unicode strings. Conceptually, a CYIString object is a sequence of Unicode charac...
Definition: YiString.h:32
CYISDFTextAtlas * GetSDFTextAtlas() const
LineStyle
Definition: YiTextEngine.h:88
Definition: YiTextEngine.h:94
Class for text rendering.
Definition: YiTextEngine.h:35
Definition: YiAbstractTextAtlas.h:15
float heightBelowBase
Definition: YiTextEngine.h:97
bool IsInitialized() const
ssize_t fontID
Definition: YiTextEngine.h:190
YI_FLOAT_RECT GetRectForTextRange(const CYITextLayout *pTextLayout, size_t startIndex, size_t endIndex, float horizontalPixelRatio, float verticalPixelRatio) const
const CYIRuntimeTypeInfo & GetDefaultTextNodeType() const
long long ssize_t
Definition: YiPredefWindows.h:21
Flags
Definition: YiTextEngine.h:38
bool SetTextAtlas(std::unique_ptr< CYITextAtlas > pAtlas)
size_t lastCodepointIndex
Definition: YiTextEngine.h:201
RenderResult RenderText(const CYITextLayout *pTextLayout, CYIBitmap *pDestination, const RenderInfo &textRenderInfo, const glm::vec2 &renderOffset, const YI_FLOAT_RECT *pTextExtents=nullptr)
CYIColor Color
Definition: YiTextEngine.h:198
The core bitmap container class used by You.i Engine.
Definition: YiBitmap.h:20
Flags flags
Definition: YiTextEngine.h:218
bool adjustsFontSizeToFit
Definition: YiTextEngine.h:223
static const size_t s_textEllipsisCodepointIndex
Definition: YiTextEngine.h:259
bool operator==(const CYIHTTPHeader &lhs, const CYIHTTPHeader &rhs)
TextType
Definition: YiTextEngine.h:56
A struct used to enable bitmask operators for an enum class type.
Definition: YiEnumBitmaskOperators.h:26
bool AddPregeneratedTextData(const CYIString &path)
float fontSizeForCachingGlyphBitmap
Definition: YiTextEngine.h:227
CYIString name
Definition: YiTextEngine.h:109
CYIString style
Definition: YiTextEngine.h:111
ssize_t GetFontId(const CYIString &fontName) const
Definition: YiTextEngine.h:186
float unadjustedFontSize
Definition: YiTextEngine.h:192
ssize_t AddFontWithOverrides(const CYIString &URL, const CYIString &fontName, const CYIString &fontFamily, const CYIString &fontStyle)
bool Init(uint16_t maxFonts, const std::map< CYITextEngine::TextType, uint16_t > &textAtlasSizes)
std::unique_ptr< CYITextSceneNode > CreateTextSceneNode() const
float leading
Definition: YiTextEngine.h:193
Class for a text atlas.
Definition: YiTextAtlas.h:16
CYITextAtlas * GetTextAtlas() const
int32_t numberOfLines
Definition: YiTextEngine.h:222
Abstract class for a text atlas.
Definition: YiAbstractTextAtlas.h:29
uint16_t GetTextAtlasSize(CYITextEngine::TextType textAtlasType=CYITextEngine::TextType::All) const
CYIString text
Definition: YiTextEngine.h:225
virtual ~CYITextEngine()
TextHeight GetTextHeight(ssize_t fontID, float fontSize) const
std::vector< CYIString > ReadFontStyles(const CYIString &url) const
Definition: YiRectangle.h:61
A scene node type that renders text.
Definition: YiTextSceneNode.h:79
Class for a signed distance field text atlas.
Definition: YiSDFTextAtlas.h:22
ssize_t engineID
Definition: YiTextEngine.h:107
Base class for abstracting the layout for text.
Definition: YiTextLayout.h:22
std::unique_ptr< CYITextLayout > GetTextLayout(const RenderInfo &rTextInfo, const std::function< std::unique_ptr< CYITextLayout >()> &textLayoutFactory=nullptr) const
const FontInfo & GetFontInfo(ssize_t fontID) const
static const float s_lineSpacingFactor
Definition: YiTextEngine.h:264
The abstract runtime representation of a C++ type.
Definition: YiRtti.h:58
bool IsFontInFile(const CYIString &familyName, const CYIString &styleName, const CYIString &URL) const
float yScale
Definition: YiTextEngine.h:220
Definition: YiTextEngine.h:117
void SetDefaultTextNodeType(const CYIRuntimeTypeInfo &nodeType)
int32_t RenderGlyphIntoAtlas(YI_GLYPH_DETAILS *pGlyph, CYIAbstractTextAtlas *pAtlas)
CYITextRenderer * GetTextRenderer() const
float minimumFontScale
Definition: YiTextEngine.h:224
GlyphsBitmapPrefetchMode
Definition: YiTextEngine.h:66
float heightAboveBase
Definition: YiTextEngine.h:96
ssize_t AddFont(const CYIString &URL)
uint32_t renderedGlyphsCount
Definition: YiTextEngine.h:253
bool operator!=(const CYIHTTPHeader &lhs, const CYIHTTPHeader &rhs)
YI_FLOAT_RECT rect
Definition: YiTextEngine.h:221
bool succeeded
Definition: YiTextEngine.h:252
A class used to represent a color value.
Definition: YiColor.h:35
float kerning
Definition: YiTextEngine.h:197
ScriptMode scriptMode
Definition: YiTextEngine.h:194
ssize_t GetFontIdFromNameAndStyle(const CYIString &fontName, const CYIString &fontStyleName, bool ignoreCase=false) const
std::vector< CYIString > GetFontStyles(ssize_t fontID) const
float offsetX
Definition: YiTextEngine.h:219
LineStyle textLineStyle
Definition: YiTextEngine.h:199
TrimmingMode
Enumeration for behavior of trimming whitespace from lines of text.
Definition: YiTextEngine.h:180
ScriptMode
Definition: YiTextEngine.h:73
CYIString family
Definition: YiTextEngine.h:110
Definition: YiTextEngine.h:247
GlyphsBitmapPrefetchMode prefetchMode
Definition: YiTextEngine.h:228
FontStyle
Definition: YiTextEngine.h:80
bool operator<(const CYIColor &lhs, const CYIColor &rhs)
CYIString filename
Definition: YiTextEngine.h:108
float baselineShift
Definition: YiTextEngine.h:195