Detailed Description

A scene node type that renders text.

The text scene node class is a primitive class that renders text using specific styling rules.

Three variants are available: CYIBitmapTextSceneNode, CYIAtlasTextSceneNode, and CYISDFAtlasTextSceneNode. The CYIBitmapTextSceneNode renders its text as a single bitmap rendered on a single quad mesh, the CYIAtlasTextSceneNode object renders glyphs into an atlas texture with a specialized mesh used to select the texture, while the CYISDFAtlasTextSceneNode object also renders glyphs into an atlas but the algorithm used for rendering the glyphs is specialized for applications that use many different fonts and sizes or that want to use animated text.

Box Text vs Point Text

Text can be configured in two different modes, which affect what bounds the text scene node will render into.

First is Box Text. Box text is the typical use case for text and can be enabled by calling the SetBoxTypeOn function. When in Box Text mode, text will be aligned such that the top of the first character is aligned with the (0,0) position of the text scene node. Box text is configured with a specific box width and box height. When justification is used, the text will be aligned within a box defined by the (0,0) position of the text scene node and the configured box size. Any text whose width exceeds the configured box width will be wrapped onto a second line. If a line does not fit within the configured box height, it will not be rendered. This includes the first line – if the first line does not fit within the configured box size, then nothing will be rendered.

Second is Point Text. Point text is used mostly for labels and can be enabled by calling the SetPointTypeOn() function. When in Point Text mode, text will be aligned horizontally around the (0,0) position, taking justification into consideration. For example, if right-justification is used, the right-most rendered character will have its right edge placed at the (0,0) position. Vertically, point text is aligned such that its baseline is at the (0,0) position. Point text can be configured with a maximum width. If the rendered text exceeds this width, the words that do not fit will not be rendered.

Both point text and box text can be configured to insert an ellipsis when some of the text does not fit within the configured bounds.

Sizing

Sizing is used by the layout system to measure and position text scene nodes. The reported size of a text scene node will be the size of the rendered text, not the configured bounds of the text. Furthermore, the reported size of a text scene node will be based on the 'glyph box' of the text rather than on a 'tight fit' of the text. This is to avoid the height of the measured text changing depending on the specific characters that are present in the text. The glyph box is roughly based on the total ascenders and descenders of each line of text (including modified leadings).

Note: Because the size of the text is based on the rendered text rather than on the specified bounds, specifying a minimum width or minimum height may result in an actual size that is below the specified minimums.

Rich Text

Text styles can be set on text scene node. Some of these styles, such as the font size and text color, can be set on a per-character basis. By default, setting those styles will apply to the whole text. However, the setter functions allow for a code point index and length to be provided so that the specific style is applied only to a range of characters. The code point index represent a character index in the text string. These are based on character code points rather than bytes since a character code point may be represented by multiple bytes.

Note: Changing the text does not update the configured text styles. Upon changing the text of a text scene node that has custom per-character styling, it may be necessary to re-configure those styles, or to reset the styles using ResetPerCharacterStyles.

The current style for a specific code point can be accessed using the getters (such as GetFontID ) while specifying a code point index to fetch the style for. If no code point index is specified, the style of the first character in the text is returned.

A specific style can also be set for the 'ellipsis' character. By default, the style of the ellipsis will be the style of the last character in the text (note: not the style of the last rendered character!). To specify a style for the ellipsis regardless of what other styles are present on the text, set a style of length 1 at code point index CYITextEngine::s_textEllipsisCodepointIndex.

Notes about the "em" Unit

An em is a unit in the field of typography, equal to the currently specified point size. For example, one em in a 16-point typeface is 16 points. Therefore, this unit is the same for all typefaces at a given point size.

Notes about Code Points

A code point is a character and can be represented by one or more code units depending on the encoding. A code unit is the number of bits an encoding uses. For example, UTF-8 would use 8 units (or bits) and UTF-16 would use 16 units.

Node Properties Specification

Though this class is not a CYISceneView, properties can still be set on it (either through code or in the After Effects workflow).

Label	Default value	Accepted values	Description
text-wrap	normal	none, normal	Specifies if text should wrap when it does not fit in the configured Box Width. Does not apply to Point Text.
text-overflow	off	off, ellipsis	Specifies if an ellipsis should be rendered when the text does not fit in the configured Box. Does not apply to Point Text.
leading	auto	positive decimal numbers	Specifies the spacing between lines of text. If absent, line spacing will be calculated from the font size. Does not apply to Point Text.
markup-parser	youi	none, youi	Specifies the markup parser to use. By default, the You.I text markup parser is used. Set to 'none' to disable parsing of text markup.
text-placeholder	false	true, false	Specifies if text should be exported. This property only affects third party tools which generate text scene nodes. When set to true, those tools will not export the user-entered text.
class	CYIAtlasTextSceneNode	CYIAtlasTextSceneNode, CYIBitmapTextSceneNode, CYISDFAtlasTextSceneNode	Used to select between Atlas, Bitmap and SDF text scene nodes.

When placed within a layout, the usual layout properties can be set to control the size of text scene nodes.

See also: CYILayout

#include <scenetree/YiTextSceneNode.h>

Inheritance diagram for CYITextSceneNode:

[legend]

Classes
struct	YI_TEXT_DEF

struct	YI_TEXT_STYLE_DEF

Public Types
enum	Justification : uint8_t { Justification::Left = 0, Justification::Right, Justification::Center }

Public Types inherited from CYISceneNode
enum	LayoutDirtyFlag : uint8_t { LayoutDirtyFlag::Clean, LayoutDirtyFlag::ChildDirty, LayoutDirtyFlag::Dirty }

enum	LayoutConfigFetchMode { LayoutConfigFetchMode::DoNotLazyInstantiate = 0, LayoutConfigFetchMode::LazyInstantiate }

enum	MeasureMode { MeasureMode::Unspecified, MeasureMode::UpTo, MeasureMode::Exactly }

enum	FetchType { FetchType::Optional = 0, FetchType::Mandatory }

typedef std::reverse_iterator< Iterator >	ReverseIterator

typedef uint16_t	DirtyFlag

Public Types inherited from CYIEventTarget
enum	SpecialEventTargetType : uint8_t { SpecialEventTargetType::None = 0x00, SpecialEventTargetType::NoPick = 0x20 }

enum	Phase : uint8_t { Phase::Bubble, Phase::Capture }

Public Member Functions
	CYITextSceneNode ()

virtual	~CYITextSceneNode ()

float	GetTextWidth ()

float	GetTextHeight ()

YI_FLOAT_RECT	CalculateTightTextRect ()

virtual YI_FLOAT_RECT_REL	CalculateGlyphBox ()

void	SetTextOffsetX (float textOffsetX)

void	SetTextMaxWidth (float maxWidth)

bool	SetFont (const CYIString &fontFamilyName, const CYIString &fontStyle, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

void	SetFontID (ssize_t fontID, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

bool	SetFontFamily (const CYIString &fontFamilyName, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

bool	SetFontStyle (const CYIString &fontStyleName, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

void	SetFontSize (int32_t fontSize, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

void	SetFontColor (const CYIColor &color, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

void	SetAllCaps (bool enable, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

void	SetScriptMode (CYITextEngine::ScriptMode scriptMode, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

void	SetBaselineShift (int32_t baselineShift, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

void	SetTracking (int32_t baselineShift, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

void	SetKerning (int32_t baselineShift, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

void	SetLeading (int32_t leading, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

void	SetEllipses (bool enable)

void	SetMaximumNumberOfLines (int32_t numberOfLines)

void	SetAdjustsFontSizeToFit (bool adjustsFontSizeToFit)

void	SetMinimumFontScale (float minimumFontScale)

void	SetMultiline (bool enable)

virtual void	SetSize (const glm::vec3 &size, bool dirtyLayout=true) override

void	SetText (const CYIString &text)

void	SetMarkedUpText (const CYIString &markedUpText, CYITextMarkupParser pMarkupParser=nullptr, const CYICustomMarkupTagsProvider pExternalTagsProvider=nullptr)

void	SetXJustify (Justification xJustify)

void	SetTrimmingMode (CYITextEngine::TrimmingMode trimmingMode)

CYITextEngine::TrimmingMode	GetTrimmingMode () const

void	SetPointTypeOn (int32_t width=0)

void	SetBoxTypeOn (int32_t boxWidth, int32_t boxHeight)

void	SetLineStyle (CYITextEngine::LineStyle textLineStyle, size_t firstCodepointIndex=0, size_t length=std::numeric_limits< size_t >::max())

float	GetTextOffsetX () const

const CYIString &	GetText () const

const CYIString &	GetMarkedUpText () const

size_t	GetLength () const

Justification	GetXJustify () const

bool	GetMultiline () const

bool	GetEllipses () const

int32_t	GetMaximumNumberOfLines () const

bool	GetAdjustsFontSizeToFit () const

float	GetMinimumFontScale () const

ssize_t	GetFontID (size_t codepointIndex=0) const

const CYIString &	GetFontFamily (size_t codepointIndex=0) const

const CYIString &	GetFontStyle (size_t codepointIndex=0) const

size_t	GetFontSize (size_t codepointIndex=0) const

const CYIColor &	GetFontColor (size_t codepointIndex=0) const

bool	IsAllCaps (size_t codepointIndex=0) const

CYITextEngine::LineStyle	GetLineStyle (size_t codepointIndex=0) const

int32_t	GetLeading (size_t codepointIndex=0) const

CYITextEngine::ScriptMode	GetScriptMode (size_t codepointIndex=0) const

int32_t	GetBaselineShift (size_t codepointIndex=0) const

int32_t	GetTracking (size_t codepointIndex=0) const

int32_t	GetKerning (size_t codepointIndex=0) const

const std::vector< YI_TEXT_STYLE_DEF > &	GetTextStyles () const

const YI_TEXT_STYLE_DEF &	GetTextStyle (size_t codepointIndex) const

void	SetTextStyle (const YI_TEXT_STYLE_DEF &style, size_t firstCodepointIndex)

void	SetTextStyles (const std::vector< YI_TEXT_STYLE_DEF > &styles)

void	SetEllipsisStyle (const YI_TEXT_STYLE_DEF &style)

void	ResetPerCharacterStyles ()

int32_t	GetBoxWidth () const

int32_t	GetBoxHeight () const

void	SetUseFontTables (bool useFontTables)

bool	IsUsingFontTables () const

bool	IsBoxType () const

bool	IsPointType () const

bool	IsTruncated () const

virtual YI_FLOAT_RECT	GetRectForTextRange (size_t startIndex, size_t endIndex, float horizontalPixelRatio, float verticalPixelRatio)

CYITextLayout::TextDirection	GetBaseTextDirection () const

CYITextLayout::TextDirection	GetCharacterTextDirection (size_t characterIndex) const

bool	IsCharacterRightToLeft (size_t characterIndex) const

bool	IsBaseRightToLeft () const

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

CYITextEngine::PositionInString	GetOffsetPosition (CYITextEngine::PositionInString initialPosition, int8_t offset)

void	SetTextLayoutFactory (std::function< std::unique_ptr< CYITextLayout >()> textLayoutFactory)

virtual void	Measure (const MeasureSpec &widthSpec, const MeasureSpec &heightSpec, const MeasureSpec &depthSpec) override

virtual void	ApplyMeasurements () override

float	GetAdjustedFontSizeScale ()

Public Member Functions inherited from CYISceneNode
	CYISceneNode ()

virtual	~CYISceneNode ()

virtual bool	Init ()

bool	IsInitialized () const

void	ForceDirty ()

void	SetDirtyFlag (DirtyFlag dirtyFlag)

DirtyFlag	GetDirtyFlag () const

DirtyFlag	GetPreviousDirtyFlag () const

const CYIString &	GetName () const

CYIString	GetUniqueName () const

void	SetSceneManager (CYISceneManager *pSceneManager)

void	SetName (const CYIString &name)

int32_t	GetID () const

void	SetID (int32_t id)

uint64_t	GetUniqueID () const

bool	AddChild (std::unique_ptr< CYISceneNode > pSceneNode)

bool	AddChild (std::unique_ptr< CYISceneNode >, size_t index)

bool	InsertChildAfter (CYISceneNode *pRefNode, std::unique_ptr< CYISceneNode > pSceneNode)

std::unique_ptr< CYISceneNode >	RemoveChild (CYISceneNode *pSceneNode)

bool	ReorderChild (size_t fromIndex, size_t toIndex)

CYITransform *	GetTransform ()

CYISceneNode *	GetParent () const

bool	ChangeParent (CYISceneNode *pParent)

CYISceneNode *	GetDrawParent () const

bool	IsAncestorOf (const CYISceneNode *pNode) const

CYISceneManager *	GetSceneManager () const

size_t	GetChildCount () const

uint32_t	GetChildCountRecursive () const

CYISceneNode *	GetChild (size_t index) const

Iterator	begin (Iterator::Mode mode=Iterator::Mode::ImmediateChildren) const

Iterator	end (Iterator::Mode mode=Iterator::Mode::ImmediateChildren) const

ReverseIterator	rbegin (Iterator::Mode mode=Iterator::Mode::ImmediateChildren) const

ReverseIterator	rend (Iterator::Mode mode=Iterator::Mode::ImmediateChildren) const

CYISceneNode *	GetChild (const CYIString &name) const

size_t	GetDrawChildCount () const

CYISceneNode *	GetDrawChild (size_t index) const

CYISceneNode *	GetDrawChildByID (int32_t id) const

template<class YI_SCENE_NODE_SUBCLASS >
YI_SCENE_NODE_SUBCLASS *	GetChild (uint32_t targetMatchedNodeCount=1) const

template<class YI_SCENE_NODE_SUBCLASS >
std::list< YI_SCENE_NODE_SUBCLASS * >	GetChildren () const

template<class YI_SCENE_NODE_SUBCLASS >
std::list< YI_SCENE_NODE_SUBCLASS * >	GetDrawChildren () const

size_t	GetIndexOfChild (const CYISceneNode *pSceneNode) const

size_t	GetIndexOfDrawChild (const CYISceneNode *pSceneNode) const

void	Show ()

void	Hide ()

void	SetVisibility (bool visible)

void	SetOpacity (float opacity)

float	GetCompositeOpacity () const

float	GetLocalOpacity () const

bool	IsVisible () const

bool	IsTrulyVisible () const

bool	IsPerceptible () const

CYISceneNode *	GetNode (CYIStringView name)

CYISceneNode *	GetNode (CYIStringView name, const CYIRuntimeTypeInfo &enforceClassType)

CYISceneNode *	GetNode (const CYIRuntimeTypeInfo &enforceClassType)

CYISceneNode *	GetNodeAfterTarget (const CYIRuntimeTypeInfo &enforceClassType, CYISceneNode *pStartAfterTarget)

template<class YI_SCENE_NODE_SUBCLASS >
YI_SCENE_NODE_SUBCLASS *	GetNode (CYIStringView name)

CYISceneNode *	GetNode (const int32_t id)

CYISceneNode *	GetNode (const int32_t id, const CYIRuntimeTypeInfo &enforceClassType)

CYISceneNode *	GetNodeWithUniqueID (uint64_t uniqueID)

template<class YI_SCENE_NODE_SUBCLASS >
bool	FindNode (YI_SCENE_NODE_SUBCLASS *&pNode, CYIStringView nodeName, FetchType type, const CYIString &tag)

std::list< CYISceneNode * >	GetNodes (CYIStringView name)

std::list< CYISceneNode * >	GetNodes (int32_t id)

std::list< CYISceneNode * >	GetNodes (const CYIRuntimeTypeInfo &enforceClassType)

template<class YI_SCENE_NODE_SUBCLASS >
const YI_SCENE_NODE_SUBCLASS *	GetNode (uint32_t targetMatchedNodeCount=1) const

template<class YI_SCENE_NODE_SUBCLASS >
YI_SCENE_NODE_SUBCLASS *	GetNode (uint32_t targetMatchedNodeCount=1)

void	SetMesh (const std::shared_ptr< CYIMesh > &pMesh)

bool	SetNPatchBitmap (const std::shared_ptr< CYIBitmap > &pNPatchBitmap)

void	ClearNPatch ()

void	SetMaterial (const std::shared_ptr< CYIMaterial > &pMaterial, size_t index=0)

void	AddEffect (const std::shared_ptr< CYIEffect > &pEffect)

void	RemoveEffect (const std::shared_ptr< CYIEffect > &pEffect)

size_t	GetEffectCount () const

const std::shared_ptr< CYIEffect > &	GetEffect (size_t index) const

void	ConnectEffectsToTimelines (const CYITimelineTrack *pTrack)

void	AddMask (std::unique_ptr< CYIMask > pMask)

std::unique_ptr< CYIMask >	RemoveMask (const CYIMask *pMask)

size_t	GetMaskCount () const

const CYIMask *	GetMask (size_t index) const

CYIMask *	GetMask (size_t index)

const std::shared_ptr< CYIMesh > &	GetMesh () const

const std::shared_ptr< CYIBitmap > &	GetNPatchBitmap () const

size_t	GetMaterialCount () const

const std::shared_ptr< CYIMaterial > &	GetMaterial (size_t index=0) const

const std::shared_ptr< IYIUniformBufferObject > &	GetShaderUniforms () const

void	SetMeshTransform (const glm::mat4 &transform)

void	DestroyChildren ()

glm::mat4	GetLocalTransform () const

glm::mat4	GetWorldTransform () const

bool	Intersects (const CYISceneNode *pNode) const

void	SetRenderTarget (const std::shared_ptr< CYIRenderTarget > &pRenderTarget)

const std::shared_ptr< CYIRenderTarget > &	GetRenderTarget () const

virtual void	OnPreBuildDrawList (std::vector< IYIRenderer::Command > pDrawList, std::vector< CYIAbstractCameraSceneNode > *pDrawWithCameraList)

virtual void	OnPostBuildDrawList (std::vector< IYIRenderer::Command > *pDrawList)

const CYIAABB &	GetWorldAABB () const

const CYIAABB &	GetLocalAABB () const

void	SetAnchorPoint (const glm::vec3 &anchorPoint)

void	SetAnchorPoint (float x, float y, float z)

void	SetAnchorPointX (float x)

void	SetAnchorPointY (float y)

void	SetAnchorPointZ (float z)

void	SetPosition (const glm::vec3 &position)

void	SetPosition (float x, float y, float z)

void	SetPositionX (float x)

void	SetPositionY (float y)

void	SetPositionZ (float z)

void	SetRotation (const glm::vec3 &rotation)

void	SetRotation (float pitchDegrees, float yawDegrees, float rollDegrees)

void	SetRotationX (float pitchDegrees)

void	SetRotationY (float yawDegrees)

void	SetRotationZ (float rollDegrees)

void	SetOrientation (float pitchDegrees, float yawDegrees, float rollDegrees)

void	SetOrientation (const glm::quat &orientation)

void	SetScale (const glm::vec3 &scale)

void	SetScale (float factorX, float factorY, float factorZ)

void	SetScaleX (float factor)

void	SetScaleY (float factor)

void	SetScaleZ (float factor)

const glm::vec3 &	GetPosition () const

const glm::vec3 &	GetScale () const

const glm::vec3 &	GetWorldScale () const

const glm::vec3 &	GetWorldSurfaceScale () const

const glm::vec3 &	GetRotation () const

const glm::quat &	GetOrientation () const

const glm::vec3 &	GetAnchorPoint () const

const glm::vec3 &	GetSize () const

const glm::vec3 &	GetInitialSize () const

void	SetMeasuredSize (const glm::vec3 &measuredSize)

const glm::vec3 &	GetMeasuredSize () const

void	SetInternalCustomTimelineValue (uint32_t trackID, const CYIVariant &value)

virtual void	SetCustomTimelineValue (uint32_t trackID, const CYIVariant &value)

void	SetClippingOn ()

void	SetClippingOff ()

bool	GetClipping () const

void	SetClippingBox (const CYIAABB &worldBox)

const CYIAABB &	GetClippingBox () const

void	StartPropertyAnimation (PropertyAnimation::Type propType, float from, float to, uint32_t durMs, CYITimeInterpolator *pTimeInterpolator=nullptr, bool dirtyLayout=true)

void	StopPropertyAnimation (PropertyAnimation::Type propType)

void	UpdateLocalSpaceCollision (CYIActionEvent *pActionEvent)

virtual bool	BroadcastEvent (const std::shared_ptr< CYIEventDispatcher > &pDispatcher, CYIEvent *pEvent)

void	UpdateEventForLocalSpace (CYIActionEvent *pActionEvent, glm::vec3 &rayOrigin, glm::vec3 &rayNonOriginPoint) const

bool	IsBoundingBoxHit (const CYIRay &worldSpaceRay) const

bool	IsMeshHit (const CYIRay &worldSpaceRay) const

void	DumpTree () const

void	StartCaptureKeyboardEvents ()

void	StopCaptureKeyboardEvents ()

void	StartCaptureTrackpadEvents ()

void	StopCaptureTrackpadEvents ()

void	StartCapturePointerEvents (uint8_t pointerID)

void	StopCapturePointerEvents (uint8_t pointerID)

bool	DrawBehindChildren (CYISceneNode pSceneNode, bool pChanged=nullptr)

bool	DrawInFrontOfChildren (CYISceneNode pSceneNode, bool pChanged=nullptr)

bool	DrawBehind (CYISceneNode pSceneNode, bool pChanged=nullptr)

bool	DrawInFront (CYISceneNode pSceneNode, bool pChanged=nullptr)

bool	IsFocusRoot () const

void	SetIsFocusRoot (bool isFocusRoot)

virtual void	OnFocusGainedInDescendants (CYISceneNode pNewNodeWithFocus, CYISceneNode pPreviousNodeWithFocus)

virtual void	FocusGainedInDescendants (CYISceneNode pNewNodeWithFocus, CYISceneNode pPreviousNodeWithFocus)

virtual void	OnFocusLostInDescendants (CYISceneNode pNewNodeWithFocus, CYISceneNode pPreviousNodeWithFocus)

virtual void	FocusLostInDescendants (CYISceneNode pNewNodeWithFocus, CYISceneNode pPreviousNodeWithFocus)

virtual void	OnFocusChangedInDescendants (CYISceneNode pNewNodeWithFocus, CYISceneNode pPreviousNodeWithFocus)

virtual void	FocusChangedInDescendants (CYISceneNode pNewNodeWithFocus, CYISceneNode pPreviousNodeWithFocus)

virtual bool	ContainsFocusableDescendant (const CYIFocusSearchOptions &options=CYIFocusSearchOptions()) const

void	SetUseLocalTransformAndAlpha (bool use)

virtual CYIOptional< CYIStringView >	GetProperty (CYIStringView propertyName) const override

bool	GetProperty (CYIStringView propertyName, CYIString *pValue) const

virtual std::map< CYIString, CYIString >	GetProperties () const override

virtual void	ForEachProperty (const std::function< void(const CYIString &, const CYIString &)> &action) const override

virtual bool	HasProperties () const override

void	SetProperty (const CYIString &propertyName, const CYIString &propertyValue)

std::shared_ptr< CYISceneNodeProxy >	GetSceneNodeProxy () const

void	SetLayoutConfig (std::unique_ptr< CYILayoutConfig > pLayoutConfig)

const CYILayoutConfig *	GetLayoutConfig (LayoutConfigFetchMode fetchMode=LayoutConfigFetchMode::LazyInstantiate) const

CYILayoutConfig *	GetLayoutConfig (LayoutConfigFetchMode fetchMode=LayoutConfigFetchMode::LazyInstantiate)

void	SetLayoutState (std::unique_ptr< CYILayoutState > pLayoutState)

const CYILayoutState *	GetLayoutState () const

CYILayoutState *	GetLayoutState ()

void	RequestLayout ()

LayoutDirtyFlag	GetLayoutDirtyFlag () const

virtual void	SetLayoutDirtyFlag (LayoutDirtyFlag flag)

virtual CYIAbstractCameraSceneNode *	FindActiveCamera (const CYISceneNode *pTargetSceneNode=nullptr) const

CYIAccessibilityAttributes::Accessible	GetAccessible () const

void	SetAccessible (CYIAccessibilityAttributes::Accessible accessible)

const CYIAccessibilityAttributes *	GetAccessibilityAttributes () const

std::unique_ptr< CYIAccessibilityAttributes >	TakeAccessibilityAttributes ()

void	SetAccessibilityAttributes (std::unique_ptr< CYIAccessibilityAttributes > pAttributes)

const CYIRenderable *	GetRenderable () const

template<typename T >
bool	CanCastTo () const

CYIAdjustmentLayerSceneNode *	GetLastAdjustmentLayer () const

Public Member Functions inherited from CYIEventTarget
	CYIEventTarget ()

virtual	~CYIEventTarget ()

bool	AddEventListener (CYIEvent::Type eventType, CYIEventHandler *pListener, CYIEventTarget::Phase phase=CYIEventTarget::Phase::Bubble)

bool	RemoveEventListener (CYIEvent::Type eventType, CYIEventHandler *pListener, CYIEventTarget::Phase phase=CYIEventTarget::Phase::Bubble)

void	SetSpecialTypeFlag (SpecialEventTargetType type)

void	ClearSpecialTypeFlag (SpecialEventTargetType type)

SpecialEventTargetType	GetSpecialTypes () const

const std::shared_ptr< CYIEventTargetProxy > &	GetProxy () const

Public Member Functions inherited from CYISignalHandler
	CYISignalHandler ()

	CYISignalHandler (const CYISignalHandler &signalHandler)

virtual	~CYISignalHandler ()

CYISignalHandler &	operator= (const CYISignalHandler &signalHandler)

void	MoveToThread (CYIThread *pThread)
	This function allows the user to override the default thread affinity to any CYIThread that may or may not be running. More...

CYIThreadHandle	GetThreadAffinity () const

void	SetThreadAffinity (const CYIThreadHandle &threadAffinity)

virtual bool	IsConnected () const

virtual bool	IsConnected (const CYISignalBase &signal) const

void	Disconnect (CYISignalBase &signal)

void	DisconnectFromAllSignals ()

Public Member Functions inherited from CYIThread::Listener
	Listener ()

virtual	~Listener ()

virtual void	OnThreadStarted (CYIThread *)

virtual void	OnThreadTerminated (CYIThread *)

virtual void	OnThreadFinished (CYIThread *)

Public Member Functions inherited from IYIPropertiesSource
virtual	~IYIPropertiesSource ()=default

bool	GetProperty (CYIStringView propertyName, CYIString *pValue) const

Protected Member Functions
const std::shared_ptr< const CYITextLayout > &	GetTextLayout (const CYITextEngine::RenderInfo &textRenderInfo)

CYITextEngine::RenderInfo	CreateTextRenderInfo ()

CYITextEngine::RenderInfo	CreateTextRenderInfo (const YI_RECT_REL &textRect)

virtual void	SpecializeTextRenderInfo (CYITextEngine::RenderInfo *pInfo)

virtual YI_FLOAT_RECT_REL	CalculateGlyphBox (const YI_RECT_REL &boxRect)

YI_FLOAT_RECT_REL	CalculateGlyphBox (const CYITextLayout *pLayout, const YI_FLOAT_RECT_REL &layoutRect) const

virtual void	PrepareToDraw ()=0

virtual void	WorldBoundingBoxUpdated () override

virtual void	UpdateEnd () override

virtual void	WorldSurfaceScaleUpdated () override

virtual CYIString	GetDumpTreeString () const override

void	SetTextDirty ()

virtual void	UpdateTextRect ()

Protected Member Functions inherited from CYISceneNode
void	Update ()

virtual void	OnUpdateBegin ()

virtual void	UpdateBegin ()

virtual void	OnUpdateEnd ()

virtual void	OnDirtyFlagChanged ()

virtual void	DirtyFlagChanged ()

virtual void	OnTransformUpdated ()

virtual void	TransformUpdated ()

virtual void	OnWorldScaleUpdated ()

virtual void	WorldScaleUpdated ()

virtual void	OnWorldSurfaceScaleUpdated ()

virtual void	OnVisibilityUpdated ()

virtual void	VisibilityUpdated ()

virtual void	OnCompositeOpacityUpdated ()

virtual void	CompositeOpacityUpdated ()

virtual void	OnWorldBoundingBoxUpdated ()

virtual void	OnLocalBoundingBoxUpdated ()

virtual void	LocalBoundingBoxUpdated ()

virtual void	OnChildAdded (CYISceneNode *pChild)

virtual void	ChildAdded (CYISceneNode *pChild)

virtual void	OnChildRemoved (CYISceneNode *pChild)

virtual void	ChildRemoved (CYISceneNode *pChild)

virtual void	OnSizeChanged ()

virtual void	SizeChanged ()

virtual void	ChildNeedsLayout ()

virtual void	LayoutDirtied ()

virtual void	OnChildVisibilityChanged (CYISceneNode *pChild)

virtual void	ChildVisibilityChanged (CYISceneNode *pChild)

virtual void	OnDrawOrderChanged ()

virtual bool	ProcessEvent (const std::shared_ptr< CYIEventDispatcher > &pDispatcher, CYIEvent *pEvent) override

LayoutDirtyFlag	GetCurrentLayoutDirtyFlag () const

void	DumpTree (int32_t indentLevel) const

virtual void	SetCustomUniforms ()

template<class T >
void	SetNodeType ()

virtual CYISceneNode *	GetNodeFromChildren (CYIStringView name)

virtual CYISceneNode *	GetNodeFromChildren (const int32_t id)

virtual CYISceneNode *	GetNodeFromChildren (const CYIRuntimeTypeInfo &enforceClassType)

CYISceneNode *	GetNodeFromChildrenAfterTarget (const CYIRuntimeTypeInfo &enforceClassType, bool pTargetReached, CYISceneNode pStartAfterTarget)

Static Protected Member Functions
static bool	HasAllCaps (const YI_TEXT_DEF &textDef)

static void	UpdateTextForAllCaps (const YI_TEXT_DEF &textDef, CYIString &text)

Protected Attributes
YI_TEXT_DEF	m_TextDef

CYIString	m_markedUpText

YI_RECT_REL	m_BoxRect

YI_RECT_REL	m_LayoutRect

YI_RECT_REL	m_MeasuredBoxRect

YI_RECT_REL	m_PreferredBoxRect

float	m_textMaxWidth

bool	m_textBufferDirty

bool	m_isBoxType

bool	m_textRectDirty

bool	m_usesFontTables

std::function< std::unique_ptr< CYITextLayout >)>	m_textLayoutFactory

Protected Attributes inherited from CYISceneNode
CYIString	m_name

CYISceneNode *	m_pParent

CYISceneNode *	m_pDrawParent

std::vector< std::unique_ptr< CYISceneNode > >	m_children

std::vector< CYISceneNode * >	m_drawChildren

std::map< CYIString, CYIString, std::less< void > >	m_Properties

std::vector< std::shared_ptr< CYIEffect > >	m_Effects

std::vector< std::unique_ptr< PropertyAnimation > >	m_propertyAnimations

float	m_localOpacity

std::unique_ptr< CYITransform >	m_pTransform

glm::vec3	m_size

glm::vec3	m_initialSize

glm::vec3	m_measuredSize

glm::vec3	m_vlsLastCollision

bool	m_clip

bool	m_localVisibility

int32_t	m_id

uint64_t	m_guid

std::unique_ptr< CYINPatch >	m_pNPatch

std::shared_ptr< CYIBitmap >	m_pNPatchBitmap

std::shared_ptr< CYIRenderable >	m_pRenderable

Protected Attributes inherited from CYIEventTarget
std::vector< EventListenerEntry >	m_listeners

SpecialEventTargetType	m_specialTypes

std::shared_ptr< CYIEventTargetProxy >	m_pEventTargetProxy

Friends
class	CYITextSceneNodePriv

Additional Inherited Members
Static Public Member Functions inherited from CYISceneNode
static void	RegisterAllSceneNodes ()

Public Attributes inherited from CYISceneNode
CYISignal< CYISceneNode *, PropertyAnimation::Type >	PropertyAnimationComplete

CYISignal< CYISceneNode , CYISceneNode >	DescendantGainedFocus
	Emitted when focus has entered this tree. The first signal parameter is the new node with focus, and the second signal parameter is the previous node with focus. More...

CYISignal< CYISceneNode , CYISceneNode >	DescendantLostFocus
	Emitted when focus has left this tree. The first signal parameter is the new node with focus, and the second signal parameter is the previous node with focus. More...

CYISignal< CYISceneNode , CYISceneNode >	DescendantsChangedFocus
	Emitted when focus has changed within this tree. This signal is called only if focus was previously within this tree and focus is now on a different node (but still within this tree). The first signal parameter is the new node with focus, and the second signal parameter is the previous node with focus. More...

CYISignal< CYIAccessibilityAttributes::Accessible >	AccessibleStateChanged
	Emitted when accessible state changed. More...

Static Public Attributes inherited from CYISceneNode
static const float	OPACITY_NOT_VISIBLE_EPSILON

static constexpr DirtyFlag	DirtyClean = 0x0000

static constexpr DirtyFlag	DirtySceneGraph = 0x0001

static constexpr DirtyFlag	DirtyVisibility = 0x0002

static constexpr DirtyFlag	DirtyOpacity = 0x0004

static constexpr DirtyFlag	DirtyLocalTransform = 0x0008

static constexpr DirtyFlag	DirtyWorldTransform = 0x0010

static constexpr DirtyFlag	DirtyUniform = 0x0020

static constexpr DirtyFlag	DirtyWorldBoundingBox = 0x0040

static constexpr DirtyFlag	DirtyMesh = 0x0080

static constexpr DirtyFlag	DirtyWorldSurfaceScale = 0x0100

static constexpr DirtyFlag	DirtyWorldScale = 0x0200

static constexpr DirtyFlag	DirtyLocalBoundingBox = 0x0400

static constexpr DirtyFlag	DirtyEverything = (DirtySceneGraph \| DirtyVisibility \| DirtyOpacity \| DirtyLocalTransform \| DirtyWorldTransform \| DirtyUniform \| DirtyWorldBoundingBox \| DirtyWorldSurfaceScale \| DirtyWorldScale \| DirtyLocalBoundingBox)

Member Enumeration Documentation

◆ Justification

enum CYITextSceneNode::Justification : uint8_t

strong

Enumerator
Left	Represents left justification for text.
Right	Represents right justification for text.
Center	Represents center justification for horizontally aligned text.

Constructor & Destructor Documentation

◆ CYITextSceneNode()

CYITextSceneNode::CYITextSceneNode ( )

◆ ~CYITextSceneNode()

virtual CYITextSceneNode::~CYITextSceneNode ( )

virtual

Member Function Documentation

◆ ApplyMeasurements()

virtual void CYITextSceneNode::ApplyMeasurements ( )

overridevirtual

Applies the measured sizes of this node's children.

Note: Typically, if ApplyMeasurements is overridden then Measure must also be overridden.; Measurements should be applied before calculating position for layout.

Warning: Subclasses that override this function must ensure that the ApplyMeasurements function of ALL children of this scene node is called.

Note: Subclasses that override this function should make use of the GetCurrentLayoutDirtyFlag() function (rather than GetLayoutDirtyFlag() ).

Reimplemented from CYISceneNode.

◆ CalculateGlyphBox() [1/3]

virtual YI_FLOAT_RECT_REL CYITextSceneNode::CalculateGlyphBox ( )

virtual

Calculates a rectangle around the text. The rectangle is calculated using the glyph box of the individual characters. The height of that glyph box remains constant even if the specific characters renderered change, thus the height of the returned will remain constant so long as the number of lines in the rendered text does not increase. The rectangle is in local coordinate space.

Note: With some characters or fonts, the rendered text may overflow the glyph box.

Reimplemented in CYISDFAtlasTextSceneNode.

◆ CalculateGlyphBox() [2/3]

virtual YI_FLOAT_RECT_REL CYITextSceneNode::CalculateGlyphBox ( const YI_RECT_REL & boxRect )

protectedvirtual

Returns a tight fitting rectangle that describes the total size of the rendered glyphs including text with multiple lines. The boxRect is used to compute the glyph box size. The returned rectangle is in local space.

Reimplemented in CYISDFAtlasTextSceneNode.

◆ CalculateGlyphBox() [3/3]

YI_FLOAT_RECT_REL CYITextSceneNode::CalculateGlyphBox	(	const CYITextLayout *	pLayout,
		const YI_FLOAT_RECT_REL &	layoutRect
	)		const

protected

Returns a tight fitting rectangle that describes the total size of the rendered glyphs including text with multiple lines. The pLayout and layoutRect is used to compute the glyph box size. The returned rectangle is in local space.

Note: This function differs from CalculateGlyphBox(const CYITextLayout *, const YI_FLOAT_RECT_REL &) in that it takes an integer rect as input.

◆ CalculateTightTextRect()

YI_FLOAT_RECT CYITextSceneNode::CalculateTightTextRect ( )

Calculates a tight rectangle around the text. The resulting rectangle is in local coordinate space.

Note: The rectangle top-left corner could contain negative values.

◆ CreateTextRenderInfo() [1/2]

CYITextEngine::RenderInfo CYITextSceneNode::CreateTextRenderInfo ( )

protected

Creates and returns a render information object describing this text scene node.

◆ CreateTextRenderInfo() [2/2]

CYITextEngine::RenderInfo CYITextSceneNode::CreateTextRenderInfo ( const YI_RECT_REL & textRect )

protected

Creates and returns a render information object describing this text scene node with a size set to textRect.

◆ GetAdjustedFontSizeScale()

float CYITextSceneNode::GetAdjustedFontSizeScale ( )

Returns the amount of scale applied to the font by the layout if AdjustsFontSizeToFit is set to true, otherwise 1 will be returned.

See also: SetAdjustsFontSizeToFit

◆ GetAdjustsFontSizeToFit()

bool CYITextSceneNode::GetAdjustsFontSizeToFit ( ) const

◆ GetBaselineShift()

int32_t CYITextSceneNode::GetBaselineShift ( size_t codepointIndex = 0 ) const

◆ GetBaseTextDirection()

CYITextLayout::TextDirection CYITextSceneNode::GetBaseTextDirection ( ) const

Returns the detected text direction.

◆ GetBoxHeight()

int32_t CYITextSceneNode::GetBoxHeight ( ) const

Returns the height of the text box - this can be updated by SetBoxTypeOn. Point text does not have a specified height and would return 0.

Note: This does not reflect the size of the actual text.

See also: SetPointTypeOn; SetBoxTypeOn

◆ GetBoxWidth()

int32_t CYITextSceneNode::GetBoxWidth ( ) const

Returns the width of the text box - this can be updated by SetPointTypeOn() and SetBoxTypeOn().

Note: This does not reflect the size of the actual text.

See also: SetPointTypeOn; SetBoxTypeOn

◆ GetCharacterTextDirection()

CYITextLayout::TextDirection CYITextSceneNode::GetCharacterTextDirection ( size_t characterIndex ) const

Returns the text direction of the character at index characterIndex. Returns TextDirection::Undefined if characterIndex is greater-than or equal to the number of characters.

◆ GetDumpTreeString()

virtual CYIString CYITextSceneNode::GetDumpTreeString ( ) const

overrideprotectedvirtual

Returns a string containing useful information about this node, displayed by DumpTree

Subclasses can implement this method to specify different or additional information. Appending to the default string is recommended.

See also: DumpTree()

Reimplemented from CYISceneNode.

◆ GetEllipses()

bool CYITextSceneNode::GetEllipses ( ) const

◆ GetFontColor()

const CYIColor& CYITextSceneNode::GetFontColor ( size_t codepointIndex = 0 ) const

◆ GetFontFamily()

const CYIString& CYITextSceneNode::GetFontFamily ( size_t codepointIndex = 0 ) const

◆ GetFontID()

ssize_t CYITextSceneNode::GetFontID ( size_t codepointIndex = 0 ) const

◆ GetFontSize()

size_t CYITextSceneNode::GetFontSize ( size_t codepointIndex = 0 ) const

◆ GetFontStyle()

const CYIString& CYITextSceneNode::GetFontStyle ( size_t codepointIndex = 0 ) const

◆ GetIndexOfPosition()

CYITextEngine::PositionInString CYITextSceneNode::GetIndexOfPosition	(	float	x,
		float	y,
		float	horizontalPixelRatio,
		float	verticalPixelRatio
	)

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

◆ GetKerning()

int32_t CYITextSceneNode::GetKerning ( size_t codepointIndex = 0 ) const

◆ GetLeading()

int32_t CYITextSceneNode::GetLeading ( size_t codepointIndex = 0 ) const

◆ GetLength()

size_t CYITextSceneNode::GetLength ( ) const

◆ GetLineStyle()

CYITextEngine::LineStyle CYITextSceneNode::GetLineStyle ( size_t codepointIndex = 0 ) const

◆ GetMarkedUpText()

const CYIString& CYITextSceneNode::GetMarkedUpText ( ) const

◆ GetMaximumNumberOfLines()

int32_t CYITextSceneNode::GetMaximumNumberOfLines ( ) const

◆ GetMinimumFontScale()

float CYITextSceneNode::GetMinimumFontScale ( ) const

◆ GetMultiline()

bool CYITextSceneNode::GetMultiline ( ) const

◆ GetOffsetPosition()

CYITextEngine::PositionInString CYITextSceneNode::GetOffsetPosition	(	CYITextEngine::PositionInString	initialPosition,
		int8_t	offset
	)

Given a position within a string initialPosition, which describes the logical position between characters and where it's represented visually, this function returns the position visually offset from that position by a number of characters described by offset. 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: If offset is negative, the output position will be offset from the input position to the left, and if positive, it will be offset to the right. In both cases, the magnitude of offset is the number of characters that the output position will be offset from the input position.

See also: GetIndexOfPosition; CYITextEngine::PositionInString

◆ GetRectForTextRange()

virtual YI_FLOAT_RECT CYITextSceneNode::GetRectForTextRange	(	size_t	startIndex,
		size_t	endIndex,
		float	horizontalPixelRatio,
		float	verticalPixelRatio
	)

virtual

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.

Reimplemented in CYISDFAtlasTextSceneNode.

◆ GetScriptMode()

CYITextEngine::ScriptMode CYITextSceneNode::GetScriptMode ( size_t codepointIndex = 0 ) const

◆ GetText()

const CYIString& CYITextSceneNode::GetText ( ) const

◆ GetTextHeight()

float CYITextSceneNode::GetTextHeight ( )

Returns the height of the rendered text in local space, including all lines in multi-line text.

Convenience method for retrieving just the height of CalculateTightTextRect.

See also: CalculateTightTextRect

◆ GetTextLayout()

const std::shared_ptr<const CYITextLayout>& CYITextSceneNode::GetTextLayout ( const CYITextEngine::RenderInfo & textRenderInfo )

protected

Returns a CYITextLayout object to use for rendering. The layout object will be cached by the text engine.

◆ GetTextOffsetX()

float CYITextSceneNode::GetTextOffsetX ( ) const

◆ GetTextStyle()

const YI_TEXT_STYLE_DEF& CYITextSceneNode::GetTextStyle ( size_t codepointIndex ) const

Finds and returns the text style that applies to the code point inde codepointIndex.

◆ GetTextStyles()

const std::vector<YI_TEXT_STYLE_DEF>& CYITextSceneNode::GetTextStyles ( ) const

Returns the list of currently-assigned per-character text styles. Each entry in the returned vector represents a range for which the specified text style applies.

◆ GetTextWidth()

float CYITextSceneNode::GetTextWidth ( )

Returns the width of the rendered text in local space, including all lines in multi-line text.

Convenience method for retrieving just the width of CalculateTightTextRect.

See also: CalculateTightTextRect

◆ GetTracking()

int32_t CYITextSceneNode::GetTracking ( size_t codepointIndex = 0 ) const

◆ GetTrimmingMode()

CYITextEngine::TrimmingMode CYITextSceneNode::GetTrimmingMode ( ) const

Returns the whitespace trimming behavior.

See also: CYITextEngine::TrimmingMode

◆ GetXJustify()

Justification CYITextSceneNode::GetXJustify ( ) const

◆ HasAllCaps()

static bool CYITextSceneNode::HasAllCaps ( const YI_TEXT_DEF & textDef )

staticprotected

Returns true if any text style definition belonging to the text definition has the all caps style applied.

◆ IsAllCaps()

bool CYITextSceneNode::IsAllCaps ( size_t codepointIndex = 0 ) const

◆ IsBaseRightToLeft()

bool CYITextSceneNode::IsBaseRightToLeft ( ) const

Returns true if the base direction of the text is right-to-left. Returns false otherwise.

Note: This function is a convenience function that calls GetBaseTextDirection.

◆ IsBoxType()

bool CYITextSceneNode::IsBoxType ( ) const

Returns true if the text is a box type.

See also: SetBoxTypeOn

◆ IsCharacterRightToLeft()

bool CYITextSceneNode::IsCharacterRightToLeft ( size_t characterIndex ) const

Returns true if the chracter at index characterIndex is in a right-to-left run of characters. Returns false otherwise or if characterIndex is greater than or equal to the number of characters.

Note: This function is a convenience function that calls GetCharacterTextDirection.

◆ IsPointType()

bool CYITextSceneNode::IsPointType ( ) const

Returns true if the text is a point type.

See also: SetPointTypeOn

◆ IsTruncated()

bool CYITextSceneNode::IsTruncated ( ) const

Returns true if the cached text layout text is truncated. This is independent of whether ellipsis is enabled or not.

Note: If there is no cached text layout, this will return false by default.

◆ IsUsingFontTables()

bool CYITextSceneNode::IsUsingFontTables ( ) const

Returns true if the font table usage is enabled.

◆ Measure()

virtual void CYITextSceneNode::Measure	(	const MeasureSpec &	widthSpec,
		const MeasureSpec &	heightSpec,
		const MeasureSpec &	depthSpec
	)

overridevirtual

Measures this scene node, considering the layout configuration constraints (if available) and the provided measure specifications. The Measure function is used by the layout system to determine the 'desired' size of elements in a container. The result of calls to this function can be accessed through the GetMeasuredSize() function.

Note: The Measure function may be called multiple times on a single scene node during a layout pass.; The measure specs passed in must take in consideration the node's scale. For example, if a node is calling the Measure function on one of its children and that child has a scale of glm::vec3(1, 3, 1), then the size of heightSpec must be divided by 3.; The measured values may exceed the provided measure specifications if the specifications cannot be met given the constraints placed on this scene node. In other words, the constraints placed on this node have a higher priority than the provided measure specifications.

Warning: Subclasses that override this function must ensure that the Measure function of ALL children of this scene node is called at least once, even if those children are hidden.

Note: Typically, if Measure is overridden then ApplyMeasurements must also be overridden.; Subclasses that override this function should make use of the GetCurrentLayoutDirtyFlag() function (rather than GetLayoutDirtyFlag() ).

Reimplemented from CYISceneNode.

◆ PrepareToDraw()

virtual void CYITextSceneNode::PrepareToDraw ( )

protectedpure virtual

Called when the bounds of the text have changed but before the text has been drawn. The work performed in this function is usually work that needs to be done in advance of rendering, such as creating a text mesh.

Implemented in CYISDFAtlasTextSceneNode, and CYIAtlasTextSceneNode.

◆ ResetPerCharacterStyles()

void CYITextSceneNode::ResetPerCharacterStyles ( )

Clears any per-character styles. After calling this function, all of the text set in this object will be rendered with the same style. The style used will be the style currently assigned to the first character.

◆ SetAdjustsFontSizeToFit()

void CYITextSceneNode::SetAdjustsFontSizeToFit ( bool adjustsFontSizeToFit )

Sets whether the text font should scale down to fit the box width and specified maximum number of lines. The maximum number of lines must be set for the text to scale. By default, the text does not scale.

Warning: The text layout will be slower if adjustsFontSizeToFit is set to true.

See also: SetMaximumNumberOfLines; SetBoxTypeOn

◆ SetAllCaps()

void CYITextSceneNode::SetAllCaps	(	bool	enable,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Specifies if text should be rendered in all caps.

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the all caps mode of the whole text.

◆ SetBaselineShift()

void CYITextSceneNode::SetBaselineShift	(	int32_t	baselineShift,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Sets the baseline shift for the text. The baseline shift specifies how far a character should be moved 'up' away from the baseline. A character with a modified baseline shift will not result in inter-line leading being modified, nor will it result in a larger (or small) glyph box being calculated. Baseline shift is independent of font size, and is specified in composition units. By default, the baseline shift is 0.

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the baseline shift of the whole text.

◆ SetBoxTypeOn()

void CYITextSceneNode::SetBoxTypeOn	(	int32_t	boxWidth,
		int32_t	boxHeight
	)

Sets the type to box type with size given by boxWidth and boxHeight,

If this text is being converted from point text in AE, also provide heightAboveBase and the anchor point of this node will be updated accordingly.

See also: GetBoxWidth; GetBoxHeight

◆ SetEllipses()

void CYITextSceneNode::SetEllipses ( bool enable )

Enables or disables ellipsis on this text scene node. If enabled and this node's text does not fit in the configured text bounds, the unrenderable text will be replaced by an ellipsis.

By default, the ellipsis uses the style of the last style in the text styles list. To set an ellipsis style indepedently of what the rest of the text is styled with, use the code point index CYITextEngine::s_textEllipsisCodepointIndex when setting text styles.

◆ SetEllipsisStyle()

void CYITextSceneNode::SetEllipsisStyle ( const YI_TEXT_STYLE_DEF & style )

Sets the text style used for ellipsis.

Note: The m_lastCodepointIndex value of the style is ignored when setting an ellipsis style.

◆ SetFont()

bool CYITextSceneNode::SetFont	(	const CYIString &	fontFamilyName,
		const CYIString &	fontStyle,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Sets the font for the text.

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the font of the whole text.

Note: Unlike the SetFontID() function, calling this function requires that the font identified by fontFamilyName and fontStyle can be found in the text engine at the time where the call to SetFont is made. Returns false without modifying the existing text styles, if the font cannot be found.

See also: SetFontID

◆ SetFontColor()

void CYITextSceneNode::SetFontColor	(	const CYIColor &	color,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Sets the font color for the text.

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the font color of the whole text.

◆ SetFontFamily()

bool CYITextSceneNode::SetFontFamily	(	const CYIString &	fontFamilyName,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Sets the font family for the text. Family refers to the typeface of the font (e.g. Arial, Calibri).

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the font of the whole text.

Note: This function will attempt to preserve the font style (i.e. regular, italic, bold) used within the text. If no font has been assigned yet (or if the specified font cannot be found), the style used will fallback to 'Regular'. Unlike the SetFontID() function, all relevant fonts are required to be present in the text engine at the time where the call to SetFontFamily is made. If the effective font used by a section of the text cannot be found (as identified by fontFamilyName and the font style for the relevant text style), this function aborts and returns false without modifying the existing text styles.

See also: SetFontID; SetFont; SetFontStyle

◆ SetFontID()

void CYITextSceneNode::SetFontID	(	ssize_t	fontID,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Sets the font ID for the text. The font ID is the ID reported for a specific font by the text engine.

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the font ID of the whole text.

See also: CYITextEngine

◆ SetFontSize()

void CYITextSceneNode::SetFontSize	(	int32_t	fontSize,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Sets the font size for the text.

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the font size of the whole text.

◆ SetFontStyle()

bool CYITextSceneNode::SetFontStyle	(	const CYIString &	fontStyleName,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Sets the font style for the text. Style refers to the font emphasis (e.g. Regular, Italic, Bold)

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the font of the whole text.

Note: This function will attempt to preserve the font family (typeface) used within the text. If no font has been assigned yet (or if the specific font cannot be found), this function aborts and returns false without modifying the existing text styles. Unlike the SetFontID() function, all relevant fonts are required to be present in the text engine at the time where the call to SetFontStyle() is made. If the effective font used by a section of text cannot be found (as identified by fontFamilyStyle and the font family for the relevant text style), this function aborts and returns false without modifying the existing text styles.

See also: SetFontID; SetFont; SetFontFamily

◆ SetKerning()

void CYITextSceneNode::SetKerning	(	int32_t	baselineShift,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Sets the kerning for the text. The kerning modifies how much space is in between the current character and the previous character, and is typically used to space to specific characters. Kerning is specified in 1/1000 em, and thus is proportional to font size. Positive values increase the inter-character spacing, and negative values decrease inter-character spacing.

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the kerning of the whole text.

◆ SetLeading()

void CYITextSceneNode::SetLeading	(	int32_t	leading,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Set the leading (line spacing) in composition units for the text. Call with a negative value to use automatic leading. By default, the leading is calculated automatically based on the font size.

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the leading of the whole text.

◆ SetLineStyle()

void CYITextSceneNode::SetLineStyle	(	CYITextEngine::LineStyle	textLineStyle,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Specifies if text should be rendered with line decoration.

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the line decoration mode of the whole text.

◆ SetMarkedUpText()

void CYITextSceneNode::SetMarkedUpText	(	const CYIString &	markedUpText,
		CYITextMarkupParser *	pMarkupParser = `nullptr`,
		const CYICustomMarkupTagsProvider *	pExternalTagsProvider = `nullptr`
	)

Parses the provided marked-up text markedUpText, assigns the parsed text to this node, and assigns parsed text styles to this node.

If pMarkupParser is null, the default You.i Engine text markup parser is used. An 'external tags' provider can optionally be supplied through the pExternalTagsProvider pointer.

Warning: If an external tags provider is supplied, it must be compatible with the provided markup parser (or be compatible with the defualt markup parser if no markup parser is provided).

Note: Existing text styles will be cleared (with the exception of the first text style), and will be replaced with the styles specified in the marked-up text. This is done even if the marked-up text contains no styling markup!; The GetText() function returns the parsed text without markup. The GetMarkedUpText() function can be used to access the original marked-up text.

See also: SetText

◆ SetMaximumNumberOfLines()

void CYITextSceneNode::SetMaximumNumberOfLines ( int32_t numberOfLines )

Sets the maximum number of lines for this node's text. To set an unlimited maximum number of lines/to remove a restriction on the number of lines, set this property to a value <= 0. If the text is box type, the displayed number of lines will not exceed the box height.

◆ SetMinimumFontScale()

void CYITextSceneNode::SetMinimumFontScale ( float minimumFontScale )

Sets the smallest possible scale a font can reach when adjustsFontSizeToFit is true. It's value is between 0.01 and 1. By default, the minimum font scale is 0.01.

See also: SetAdjustsFontSizeToFit

◆ SetMultiline()

void CYITextSceneNode::SetMultiline ( bool enable )

Sets the wrapping behaviour of the text. If enable is true, text will wrap onto a second line if the text is wider than the box width. If false, only one line of text will be rendered. By default, text does not wrap.

◆ SetPointTypeOn()

void CYITextSceneNode::SetPointTypeOn ( int32_t width = 0 )

Sets the type to point type. if width is specified and greater than 0, this will count as the maximum width of the node.

The box size of this node will be updated to have a width of width and a height of 0.

Multiline is turned off by default for point text.

See also: GetBoxWidth; GetBoxHeight

◆ SetScriptMode()

void CYITextSceneNode::SetScriptMode	(	CYITextEngine::ScriptMode	scriptMode,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Sets the script mode for the text. The script mode is used to specify if some text should be rendered as superscript, subscript or a regular text.

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the script mode of the whole text.

◆ SetSize()

virtual void CYITextSceneNode::SetSize	(	const glm::vec3 &	size,
		bool	dirtyLayout = `true`
	)

overridevirtual

Sets the size of this node to size.

Note: Changing the size of a node may affect other properties of the node (such as the mesh size or the node's scale); Subclasses that override this function must call the OnSizeChanged function if the size changed. Subclasses that override this function should dirty the layout if the size changed and dirtyLayout is true.

Reimplemented from CYISceneNode.

Reimplemented in CYIBitmapTextSceneNode.

◆ SetText()

void CYITextSceneNode::SetText ( const CYIString & text )

Sets the text. If this node is point type, passing in text which contains a newline will turn multiline mode on. Setting text without a newline will clear multiline mode.

SetMultiline can be called after SetText to override the automatic multiline setting.

Note: The text will be modified if unicode normalization is required, in which case text will be normalized, and any calls to GetText() will return the normalized text.

Existing text styles will be preserved when new text is set. Use CYITextSceneNode::ResetPerCharacterStyles() to clear existing text styles.

◆ SetTextDirty()

void CYITextSceneNode::SetTextDirty ( )

protected

Sets the text node dirty state, dirties the screne graph and invalidates the layout.

◆ SetTextLayoutFactory()

void CYITextSceneNode::SetTextLayoutFactory ( std::function< std::unique_ptr< CYITextLayout >()> textLayoutFactory )

Set a text layout factory which allows overriding the concrete CYITextLayout implementation that is used by default. This is done on a per-node basis meaning different CYITextSceneNode instances can use different CYITextLayout implementations.

◆ SetTextMaxWidth()

void CYITextSceneNode::SetTextMaxWidth ( float maxWidth )

Sets the maximum width in local space. This value will override the calculated text width, after box width has been applied. Use this in combination with SetTextOffsetX to show only a specified area of the text node.

See also: SetTextOffsetX

◆ SetTextOffsetX()

void CYITextSceneNode::SetTextOffsetX ( float textOffsetX )

Sets the first position in the stored text string to show in local space. Use this in combination with SetTextMaxWidth to show only a specified area of the text node.

See also: SetTextMaxWidth

◆ SetTextStyle()

void CYITextSceneNode::SetTextStyle	(	const YI_TEXT_STYLE_DEF &	style,
		size_t	firstCodepointIndex
	)

Sets the text style at code point index firstCodepointIndex to style.

Some existing text styles may be removed if the provided style completely 'covers' them. Does nothing if the provided style's m_lastCodepointIndex value is smaller or equal to codepointIndex (but a warning will be logged).

◆ SetTextStyles()

void CYITextSceneNode::SetTextStyles ( const std::vector< YI_TEXT_STYLE_DEF > & styles )

Replaces the existing texts styles with those in the provided vector styles.

The last style's codepointIndex will be changed to std::numeric_limits<uint32_t>::max() if it isn't already. The styles are expected to be ordered in increasing value of m_lastCodepointIndex – out of order styles, and those with duplicate m_lastCodepointIndex values, will be ignored (and a warning will be logged). Does nothing if the provided vector is empty (but a warning will be logged).

Note: Calling this function will also replace the ellipsis style, if such a style exists.

See also: SetEllipsisStyle

◆ SetTracking()

void CYITextSceneNode::SetTracking	(	int32_t	baselineShift,
		size_t	firstCodepointIndex = `0`,
		size_t	length = `std::numeric_limits< size_t >::max()`
	)

Sets the tracking for the text. The tracking modifies how much space is in between the current character and the next character, and is typically used on whole words. Tracking is ignored on the last character in a line of text. Tracking is specified in 1/1000 em, and thus is proportional to font size. Positive values increase the inter-character spacing, and negative values decrease inter-character spacing.

Optionally, a range of characters to which the property applies can be specified using firstcodepointIndex and length. By default, calling this function changes the tracking of the whole text.

◆ SetTrimmingMode()

void CYITextSceneNode::SetTrimmingMode ( CYITextEngine::TrimmingMode trimmingMode )

Sets the whitespace trimming behavior.

Note: See CYITextEngine::TrimmingMode::Default for a description of the default behavior if the trimming mode is not manually set.

See also: CYITextEngine::TrimmingMode

◆ SetUseFontTables()

void CYITextSceneNode::SetUseFontTables ( bool useFontTables )

Turns the usage of font tables on or off. If font table usage is off, kerning and ligatures will not be available.

Note: Font table usage is on by default.

◆ SetXJustify()

void CYITextSceneNode::SetXJustify ( Justification xJustify )

Sets the text alignment. The text can be either left-aligned, right-aligned, or centered. The mode of the text (point text or box text) affects what the text is aligned around: for box text, the text is aligned between the configured box bounds. For point text, the text is aligned around the (0,0) point of the text node. The default justification is left-aligned.

◆ SpecializeTextRenderInfo()

virtual void CYITextSceneNode::SpecializeTextRenderInfo ( CYITextEngine::RenderInfo * pInfo )

protectedvirtual

Adds implementation-specific data to pInfo.

Reimplemented in CYISDFAtlasTextSceneNode, CYIAtlasTextSceneNode, and CYIBitmapTextSceneNode.

◆ UpdateEnd()

virtual void CYITextSceneNode::UpdateEnd ( )

overrideprotectedvirtual

This hook provides subclasses a means to do operations subsequent to update. This hook is called after all children of the current node have been updated, and after all other update hooks have been called.

Warning: The dirty flag will be cleared prior to calling this function to allow new dirty state to be recorded from this function. If querying information about the dirty state of the node, use GetPreviousDirtyFlag().; Overrides must call the base class implementation.

See also: Update(); OnUpdateEnd()

Reimplemented from CYISceneNode.

◆ UpdateTextForAllCaps()

static void CYITextSceneNode::UpdateTextForAllCaps	(	const YI_TEXT_DEF &	textDef,
		CYIString &	text
	)

staticprotected

Applies the all caps styles, if it has been set, to the supplied text.

◆ UpdateTextRect()

virtual void CYITextSceneNode::UpdateTextRect ( )

protectedvirtual

Updates the text rectangle for the text type. Depending on the text type (point or box), the values for width and height may not be calculated until the mesh is created.

◆ WorldBoundingBoxUpdated()

virtual void CYITextSceneNode::WorldBoundingBoxUpdated ( )

overrideprotectedvirtual

Called by Update() when the world bounding box update process is complete. Subclasses may overload this function to do post-processing.

Warning: The dirty flag will be cleared prior to calling this function to allow new dirty state to be recorded from this function. If querying information about the dirty state of the node, use GetPreviousDirtyFlag().; Overrides must call the base class implementation.

See also: Update(); OnWorldBoundingBoxUpdated()

Reimplemented from CYISceneNode.

◆ WorldSurfaceScaleUpdated()

virtual void CYITextSceneNode::WorldSurfaceScaleUpdated ( )

overrideprotectedvirtual

Called by Update() when the transform update process is complete and only when the world surface scale has changed. Subclasses may overload this function to do post-processing.

Warning: The dirty flag will be cleared prior to calling this function to allow new dirty state to be recorded from this function. If querying information about the dirty state of the node, use GetPreviousDirtyFlag().

See also: GetWorldSurfaceScale

Warning: Overrides must call the base class implementation.

See also: Update(); OnWorldSurfaceScaleUpdated()

Reimplemented from CYISceneNode.

Reimplemented in CYISDFAtlasTextSceneNode.

Friends And Related Function Documentation

◆ CYITextSceneNodePriv

friend class CYITextSceneNodePriv

friend

Member Data Documentation

◆ m_BoxRect

YI_RECT_REL CYITextSceneNode::m_BoxRect

protected

Box dimensions in local space. Used for point type text as well

◆ m_isBoxType

bool CYITextSceneNode::m_isBoxType

protected

Flag to indicate if the text node type is box

◆ m_LayoutRect

YI_RECT_REL CYITextSceneNode::m_LayoutRect

protected

Used when calculating the glyph box

◆ m_markedUpText

CYIString CYITextSceneNode::m_markedUpText

protected

Marked-up text for this node.

See also: SetMarkedUpText

◆ m_MeasuredBoxRect

YI_RECT_REL CYITextSceneNode::m_MeasuredBoxRect

protected

Measured size for the text

◆ m_PreferredBoxRect

YI_RECT_REL CYITextSceneNode::m_PreferredBoxRect

protected

Original box type size

◆ m_textBufferDirty

bool CYITextSceneNode::m_textBufferDirty

protected

Flag to indicate that the content has been changed and associated dimensions need to be recalculated

◆ m_TextDef

YI_TEXT_DEF CYITextSceneNode::m_TextDef

protected

Text definition for this node

◆ m_textLayoutFactory

std::function<std::unique_ptr<CYITextLayout>)> CYITextSceneNode::m_textLayoutFactory

protected

◆ m_textMaxWidth

float CYITextSceneNode::m_textMaxWidth

protected

Maximum width of the text in local space

◆ m_textRectDirty

bool CYITextSceneNode::m_textRectDirty

protected

Flag indicating the layout needs to be recalculated

◆ m_usesFontTables

bool CYITextSceneNode::m_usesFontTables

protected

Flag indicating that FreeType font tables are being used

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

scenetree/YiTextSceneNode.h

Detailed Description

Classes

Public Types

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Member Enumeration Documentation

◆ Justification

Constructor & Destructor Documentation

◆ CYITextSceneNode()

◆ ~CYITextSceneNode()

Member Function Documentation

◆ ApplyMeasurements()

◆ CalculateGlyphBox() [1/3]

◆ CalculateGlyphBox() [2/3]

◆ CalculateGlyphBox() [3/3]

◆ CalculateTightTextRect()

◆ CreateTextRenderInfo() [1/2]

◆ CreateTextRenderInfo() [2/2]

◆ GetAdjustedFontSizeScale()

◆ GetAdjustsFontSizeToFit()

◆ GetBaselineShift()

◆ GetBaseTextDirection()

◆ GetBoxHeight()

◆ GetBoxWidth()

◆ GetCharacterTextDirection()

◆ GetDumpTreeString()

◆ GetEllipses()

◆ GetFontColor()

◆ GetFontFamily()

◆ GetFontID()

◆ GetFontSize()

◆ GetFontStyle()

◆ GetIndexOfPosition()

◆ GetKerning()

◆ GetLeading()

◆ GetLength()

◆ GetLineStyle()

◆ GetMarkedUpText()

◆ GetMaximumNumberOfLines()

◆ GetMinimumFontScale()

◆ GetMultiline()

◆ GetOffsetPosition()

◆ GetRectForTextRange()

◆ GetScriptMode()

◆ GetText()

◆ GetTextHeight()

◆ GetTextLayout()

◆ GetTextOffsetX()

◆ GetTextStyle()

◆ GetTextStyles()

◆ GetTextWidth()

◆ GetTracking()

◆ GetTrimmingMode()

◆ GetXJustify()

◆ HasAllCaps()

◆ IsAllCaps()

◆ IsBaseRightToLeft()

◆ IsBoxType()

◆ IsCharacterRightToLeft()

◆ IsPointType()

◆ IsTruncated()

◆ IsUsingFontTables()

◆ Measure()

◆ PrepareToDraw()

◆ ResetPerCharacterStyles()

◆ SetAdjustsFontSizeToFit()

◆ SetAllCaps()

◆ SetBaselineShift()

◆ SetBoxTypeOn()

◆ SetEllipses()

◆ SetEllipsisStyle()

◆ SetFont()

◆ SetFontColor()

◆ SetFontFamily()

◆ SetFontID()

◆ SetFontSize()