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 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

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

enum CYITextEngine::FontStyle

strong

Enumerator
Regular
Bold
BoldItalic
Italic

◆ GlyphsBitmapPrefetchMode

enum CYITextEngine::GlyphsBitmapPrefetchMode : uint8_t

strong

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

enum CYITextEngine::LineStyle

strong

Enumerator
None
Underline

◆ ScriptMode

enum CYITextEngine::ScriptMode

strong

Enumerator
Regular
Subscript
Superscript

◆ TextType

enum CYITextEngine::TextType

strong

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

enum CYITextEngine::TrimmingMode

strong

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 &	textInfo,
		const std::function< std::unique_ptr< CYITextLayout >()> &	textLayoutFactory = `nullptr`
	)		const

Returns a newly created text layout that is layed out using the supplied textInfo. 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:

graphics/YiTextEngine.h

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Attributes

Member Enumeration Documentation

◆ Flags

◆ FontStyle

◆ GlyphsBitmapPrefetchMode

◆ LineStyle

◆ ScriptMode

◆ TextType

◆ TrimmingMode

Constructor & Destructor Documentation

◆ CYITextEngine()

◆ ~CYITextEngine()

Member Function Documentation

◆ AddFont() [1/5]

◆ AddFont() [2/5]

◆ AddFont() [3/5]

◆ AddFont() [4/5]

◆ AddFont() [5/5]

◆ AddFontWithOverrides()

◆ AddPregeneratedTextData() [1/2]

◆ AddPregeneratedTextData() [2/2]

◆ CreateTextSceneNode()

◆ FindFontByFamilyName()

◆ GetCharacterIndex()

◆ GetDefaultTextNodeType()

◆ GetFontId() [1/2]

◆ GetFontId() [2/2]

◆ GetFontIdFromNameAndStyle()

◆ GetFontInfo()

◆ GetFontStyles() [1/2]

◆ GetFontStyles() [2/2]

◆ GetIndexOfPosition()

◆ GetNumFonts()

◆ GetRectForTextRange()

◆ GetSDFTextAtlas()

◆ GetTextAtlas()

◆ GetTextAtlasSize()

◆ GetTextHeight()

◆ GetTextLayout()

◆ GetTextRenderer()

◆ Init()

◆ IsFontInFile()

◆ IsInitialized()

◆ ReadFontStyles() [1/2]

◆ ReadFontStyles() [2/2]

◆ RenderGlyphIntoAtlas()

◆ RenderText()

◆ SetDefaultTextNodeType()

◆ SetSDFTextAtlas()

◆ SetTextAtlas()

Member Data Documentation

◆ s_lineSpacingFactor

◆ s_textEllipsisCodepointIndex