You.i Engine
CYITextEngine Class Reference

Detailed Description

Class for text rendering.

#include <graphics/YiTextEngine.h>

Classes

struct  FontInfo
 
class  PositionInString
 
struct  RenderInfo
 Struct used to pass information when rendering text. More...
 
struct  RenderResult
 
struct  TextHeight
 
struct  TextStyle
 

Public Types

enum  Flags {
  Flags::None = 0x00,
  Flags::Left = 0x01,
  Flags::Center = 0x02,
  Flags::Right = 0x04,
  Flags::Ellipses = 0x08,
  Flags::Multiline = 0x10,
  Flags::UserWidth = 0x20,
  Flags::FontTables = 0x40,
  Flags::CacheGlyphBitmapOnFirstRequest = 0x80,
  Flags::CacheGlyphBitmapAlways = 0x100,
  Flags::DefaultTrimming = 0x200
}
 
enum  TextType {
  TextType::Atlas = 0,
  TextType::SDFAtlas,
  TextType::All
}
 
enum  GlyphsBitmapPrefetchMode : uint8_t {
  GlyphsBitmapPrefetchMode::NoPrefetch,
  GlyphsBitmapPrefetchMode::Bitmap,
  GlyphsBitmapPrefetchMode::SDF
}
 
enum  ScriptMode {
  ScriptMode::Regular = 0,
  ScriptMode::Subscript,
  ScriptMode::Superscript
}
 
enum  FontStyle {
  FontStyle::Regular = 0,
  FontStyle::Bold,
  FontStyle::BoldItalic,
  FontStyle::Italic
}
 
enum  LineStyle {
  LineStyle::None = 0,
  LineStyle::Underline
}
 
enum  TrimmingMode {
  TrimmingMode::Default = 0,
  TrimmingMode::None = 1
}
 Enumeration for behavior of trimming whitespace from lines of text. More...
 

Public Member Functions

 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 FontInfoGetFontInfo (ssize_t fontID) const
 
std::vector< CYIStringGetFontStyles (ssize_t fontID) const
 
std::vector< CYIStringGetFontStyles (const CYIString &fontFamilyName) const
 
std::vector< CYIStringReadFontStyles (const CYIString &url) const
 
std::vector< CYIStringReadFontStyles (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
 
CYITextAtlasGetTextAtlas () const
 
CYISDFTextAtlasGetSDFTextAtlas () 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< CYITextLayoutGetTextLayout (const RenderInfo &rTextInfo, 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 CYIRuntimeTypeInfoGetDefaultTextNodeType () const
 
std::unique_ptr< CYITextSceneNodeCreateTextSceneNode () const
 

Static Public Attributes

static const size_t s_textEllipsisCodepointIndex
 
static const float s_lineSpacingFactor
 

Member Enumeration Documentation

◆ Flags

enum CYITextEngine::Flags
strong
Enumerator
None 
Left 
Center 
Right 
Ellipses 
Multiline 
UserWidth 
FontTables 
CacheGlyphBitmapOnFirstRequest 
CacheGlyphBitmapAlways 
DefaultTrimming 

◆ FontStyle

Enumerator
Regular 
Bold 
BoldItalic 
Italic 

◆ GlyphsBitmapPrefetchMode

The glyphs bitmap prefetch mode. This is used when querying glyph metrics when it is known that a bitmap of a specific type will later be needed.

Enumerator
NoPrefetch 

No bitmap is prefeched.

Bitmap 

A regular bitmap is prefetched.

SDF 

A bitmap with SDF applied to it is prefetched.

◆ LineStyle

Enumerator
None 
Underline 

◆ ScriptMode

Enumerator
Regular 
Subscript 
Superscript 

◆ TextType

Text types supported by the text engine.

Enumerator
Atlas 

Standard atlas text.

See also
CYITextAtlas
CYIAtlasTextSceneNode
SDFAtlas 

Signed distance field atlas text.

See also
CYISDFTextAtlas
CYISDFAtlasTextSceneNode
All 

Value that represents all above text types. Used within APIs to specify that all text types should be operated on.

◆ TrimmingMode

Enumeration for behavior of trimming whitespace from lines of text.

Enumerator
Default 
None 

Constructor & Destructor Documentation

◆ CYITextEngine()

CYITextEngine::CYITextEngine ( )

◆ ~CYITextEngine()

virtual CYITextEngine::~CYITextEngine ( )
virtual

Member Function Documentation

◆ AddFont() [1/5]

ssize_t CYITextEngine::AddFont ( const CYIString URL)

Add a font

◆ AddFont() [2/5]

ssize_t CYITextEngine::AddFont ( const CYIString URL,
const CYIString fontName 
)

Add a font. If the font file contains multiple styles, only the first style will be loaded and a warning will be logged.

See also
AddFont(const CYIString&, const CYIString&, const CYIString&)

◆ AddFont() [3/5]

ssize_t CYITextEngine::AddFont ( const CYIString URL,
const CYIString fontName,
const CYIString fontStyle 
)

Add a font. If the font file contains multiple styles and fontStyle is non-empty, that font style is loaded. If fontStyle is non-empty and that style cannot be found in the font file, a warning is logged and the first style is loaded instead.

◆ AddFont() [4/5]

ssize_t CYITextEngine::AddFont ( const uint8_t *  pFontData,
size_t  dataSize 
)

Add a font from memory. If the font file contains multiple styles, only the first style will be loaded and a warning will be logged.

See also
AddFont(const uint8_t *, size_t, const CYIString&, const CYIString&)

◆ AddFont() [5/5]

ssize_t CYITextEngine::AddFont ( const uint8_t *  pFontData,
size_t  dataSize,
const CYIString fontName,
const CYIString fontStyle 
)

Add a font from memory. If the font contains multiple styles and fontStyle is non-empty, that font style is loaded. If fontStyle is non-empty and that style cannot be found in the font, a warning is logged and the first style is loaded instead.

◆ AddFontWithOverrides()

ssize_t CYITextEngine::AddFontWithOverrides ( const CYIString URL,
const CYIString fontName,
const CYIString fontFamily,
const CYIString fontStyle 
)

Add a font. This overrides the font family and font style from the font itself and instead uses the provided values.

◆ AddPregeneratedTextData() [1/2]

bool CYITextEngine::AddPregeneratedTextData ( const CYIString path)

Adds pregenerated text data. Pregenerated text data can be used to accelerate first-time text rendering. If a pregenerated text data file has already been loaded from the specified path, false is returned. If the specified file cannot be found, false is returned. It is not necessary for an associated font to have been loaded prior to this function being called.

Note
It is not necessary to manually add pregenerated text data files when those files exist in the same folder as the fonts being added. As long as the pregenerated text data file has the same name as a font being loaded (excluding the .pregen extension), the pregenerated text data file will be added to the text engine automatically.

◆ AddPregeneratedTextData() [2/2]

bool CYITextEngine::AddPregeneratedTextData ( const uint8_t *  pPregeneratedTextData,
size_t  dataSize 
)

Adds pregenerated text data. Pregenerated text data can be used to accelerate first-time text rendering. If pregenerated text data that matches this data's checksum has already been added, false is returned. It is not necessary for an associated font to have been loaded prior to this function being called.

Note
This function copies the provided data into the text engine.

◆ CreateTextSceneNode()

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

Creates an instance of a sub-class of CYITextSceneNode, using the currently-configured default text node type. The returned scene node will not have had its CYISceneNode::Init() function called.

See also
SetDefaultTextNodeType

◆ FindFontByFamilyName()

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

Attempts to find a font with similar properties as the fontFamilyName. Returns the font ID for the first available font if no matches are found. Returns -1 if no fonts are available.

◆ GetCharacterIndex()

size_t CYITextEngine::GetCharacterIndex ( ssize_t  fontID,
uint32_t  character 
) const

Retrieves the index of the given character in the font renderer. The index is managed by the font renderer.

◆ GetDefaultTextNodeType()

const CYIRuntimeTypeInfo& CYITextEngine::GetDefaultTextNodeType ( ) const

◆ GetFontId() [1/2]

ssize_t CYITextEngine::GetFontId ( const CYIString fontName) const

Returns the font ID for the specified font name fontName. Returns -1 if the font cannot be found.

◆ GetFontId() [2/2]

ssize_t CYITextEngine::GetFontId ( const CYIString fontFamilyName,
const CYIString fontStyleName,
bool  ignoreCase = false 
) const

Returns the font ID for the specified font family fontFamilyName and font style fontStyleName . If ignoreCase is true, the search will be case insensitive. Returns -1 if the font cannot be found.

◆ GetFontIdFromNameAndStyle()

ssize_t CYITextEngine::GetFontIdFromNameAndStyle ( const CYIString fontName,
const CYIString fontStyleName,
bool  ignoreCase = false 
) const

Returns the font ID for the specified font name fontName and font style fontStyleName. If ignoreCase is true, the search will be case insensitive. Returns -1 if the font cannot be found.

◆ GetFontInfo()

const FontInfo& CYITextEngine::GetFontInfo ( ssize_t  fontID) const

Returns the font information object for the font with engine ID fontID. Returns an empty font information object if the provided font ID does not exist.

◆ GetFontStyles() [1/2]

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

Returns a list of all available font styles for fonts that have the same font family name as the font with font ID fontID .

◆ GetFontStyles() [2/2]

std::vector<CYIString> CYITextEngine::GetFontStyles ( const CYIString fontFamilyName) const

Returns a list of all available font styles for family name fontFamilyName .

◆ GetIndexOfPosition()

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

Returns the index of the space between two characters in the text closest to the specified local coordinate position, relative to the top left corner of the node containing the text. The return value is an instance of CYITextEngine::PositionInString, which contains information about the logical position in the string, and where it should be visually represented.

Note
The horizontal pixel ratio horizontalPixelRatio and vertical pixel ratio verticalPixelRatio can be obtained from the camera and are based on the scaling type used to load the After Effects composition.
Currently this is only supported for single line text but the y position y and vertical pixel ratio verticalPixelRatio are added for future multiline support.
See also
CYITextEngine::PositionInString

◆ GetNumFonts()

uint32_t CYITextEngine::GetNumFonts ( ) const

Get the number of fonts loaded

◆ GetRectForTextRange()

YI_FLOAT_RECT CYITextEngine::GetRectForTextRange ( const CYITextLayout pTextLayout,
size_t  startIndex,
size_t  endIndex,
float  horizontalPixelRatio,
float  verticalPixelRatio 
) const

Get the rect surrounding characters from startIndex to endIndex for the cached layout of text that has been rendered.

Note
For bidirectional text, the resulting rect will span the leftmost character, to the rightmost character, potentially also surrounding characters outside of the range of character indices.
If no text has been rendered, by calling RenderText previously, or invalid index values are passed then the rect will be set to 0 for all values.

◆ GetSDFTextAtlas()

CYISDFTextAtlas* CYITextEngine::GetSDFTextAtlas ( ) const

Returns the SDF text atlas. This will return NULL if it doesn't exist.

◆ GetTextAtlas()

CYITextAtlas* CYITextEngine::GetTextAtlas ( ) const

Returns the regular text atlas. This will return NULL if it doesn't exist.

◆ GetTextAtlasSize()

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

Returns the text atlas pixel dimension that the engine is configured to use for the specified textAtlasType. Text atlases are square so this dimension represents both width and height.

Note
If textAtlasType is CYITextEngine::TextType::All and all text atlases are not the same size 0 will be returned, each atlas size will need to be queried individually in this case.

◆ GetTextHeight()

TextHeight CYITextEngine::GetTextHeight ( ssize_t  fontID,
float  fontSize 
) const

Get the total height of a font

◆ GetTextLayout()

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

Returns a newly created text layout that is layed out using the supplied rTextInfo. An optional textLayoutFactory function can be provided, which allows overriding the concrete CYITextLayout type that is created by default.

◆ GetTextRenderer()

CYITextRenderer* CYITextEngine::GetTextRenderer ( ) const

◆ Init()

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

Initializes the text engine with the maximuim number of fonts to cache and the square pixel dimension of each text atlas.

Note
If CYITextEngine::TextType::All is contained in textAtlasSizes

◆ IsFontInFile()

bool CYITextEngine::IsFontInFile ( const CYIString familyName,
const CYIString styleName,
const CYIString URL 
) const

Returns true if the combination of familyName and styleName is the first one found in the file specified by URL

◆ IsInitialized()

bool CYITextEngine::IsInitialized ( ) const
See also
Init

◆ ReadFontStyles() [1/2]

std::vector<CYIString> CYITextEngine::ReadFontStyles ( const CYIString url) const

Returns a list of all available font styles in the font file specified by url.

◆ ReadFontStyles() [2/2]

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

Returns a list of all available font styles in the font data pFontData.

◆ RenderGlyphIntoAtlas()

int32_t CYITextEngine::RenderGlyphIntoAtlas ( YI_GLYPH_DETAILS pGlyph,
CYIAbstractTextAtlas pAtlas 
)

New rendering creating from atlas

Warning
This function does not check if the glyph is already present in the text atlas for performance reason. It is the user's responsibility to make sure that the texture atlas is not available before calling this function. The check can be done by calling CYITextEngine::GetFontAtlasTexture, which would return nullptr when the glyph is not available in the text atlas.

◆ RenderText()

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

Original rendering for simple word into single bitmap. The text must have been laid-out already in the pTextLayout object.

◆ SetDefaultTextNodeType()

void CYITextEngine::SetDefaultTextNodeType ( const CYIRuntimeTypeInfo nodeType)

Sets the default text node type. When text is exported from After Effects it will be imported into You.i Engine as CYISDFAtlasTextSceneNode by default. Calling this setter will override that default import behavior, as well as the behavior of CreateTextSceneNode(). nodeType must be a sub-type of CYITextSceneNode.

◆ SetSDFTextAtlas()

bool CYITextEngine::SetSDFTextAtlas ( std::unique_ptr< CYISDFTextAtlas pAtlas)

Sets the SDF text atlas. Returns false if the current SDF atlas is not NULL.

◆ SetTextAtlas()

bool CYITextEngine::SetTextAtlas ( std::unique_ptr< CYITextAtlas pAtlas)

Sets the regular text atlas. Returns false if the current atlas is not NULL.

Member Data Documentation

◆ s_lineSpacingFactor

const float CYITextEngine::s_lineSpacingFactor
static

The factor used to calculate the spacing between lines of text. This is multiplied by a line's font size to get a line's leading value.

◆ s_textEllipsisCodepointIndex

const size_t CYITextEngine::s_textEllipsisCodepointIndex
static

The codepoint index that should be used to set a style for the 'ellipsis' text.


The documentation for this class was generated from the following file: