You.i Engine
CYITextSceneNode Class Referenceabstract

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:

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< IteratorReverseIterator
 
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 &rText)
 
void SetMarkedUpText (const CYIString &rMarkedUpText, 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 CYIStringGetText () const
 
const CYIStringGetMarkedUpText () 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 CYIStringGetFontFamily (size_t codepointIndex=0) const
 
const CYIStringGetFontStyle (size_t codepointIndex=0) const
 
size_t GetFontSize (size_t codepointIndex=0) const
 
const CYIColorGetFontColor (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_DEFGetTextStyle (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 CYIStringGetName () 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< CYISceneNodeRemoveChild (CYISceneNode *pSceneNode)
 
bool ReorderChild (size_t fromIndex, size_t toIndex)
 
CYITransformGetTransform ()
 
CYISceneNodeGetParent () const
 
bool ChangeParent (CYISceneNode *pParent)
 
CYISceneNodeGetDrawParent () const
 
bool IsAncestorOf (const CYISceneNode *pNode) const
 
CYISceneManagerGetSceneManager () const
 
size_t GetChildCount () const
 
uint32_t GetChildCountRecursive () const
 
CYISceneNodeGetChild (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
 
CYISceneNodeGetChild (const CYIString &name) const
 
size_t GetDrawChildCount () const
 
CYISceneNodeGetDrawChild (size_t index) const
 
CYISceneNodeGetDrawChildByID (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
 
CYISceneNodeGetNode (CYIStringView name)
 
CYISceneNodeGetNode (CYIStringView name, const CYIRuntimeTypeInfo &enforceClassType)
 
CYISceneNodeGetNode (const CYIRuntimeTypeInfo &enforceClassType)
 
CYISceneNodeGetNodeAfterTarget (const CYIRuntimeTypeInfo &enforceClassType, CYISceneNode *pStartAfterTarget)
 
template<class YI_SCENE_NODE_SUBCLASS >
YI_SCENE_NODE_SUBCLASS * GetNode (CYIStringView name)
 
CYISceneNodeGetNode (const int32_t id)
 
CYISceneNodeGetNode (const int32_t id, const CYIRuntimeTypeInfo &enforceClassType)
 
CYISceneNodeGetNodeWithUniqueID (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< CYIMaskRemoveMask (const CYIMask *pMask)
 
size_t GetMaskCount () const
 
const CYIMaskGetMask (size_t index) const
 
CYIMaskGetMask (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 &rTransform)
 
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 CYIAABBGetWorldAABB () const
 
const CYIAABBGetLocalAABB () 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 &rWorldBox)
 
const CYIAABBGetClippingBox () 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 &rWorldSpaceRay) const
 
bool IsMeshHit (const CYIRay &rWorldSpaceRay) 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< CYIStringViewGetProperty (CYIStringView propertyName) const override
 
bool GetProperty (CYIStringView propertyName, CYIString *pValue) const
 
virtual std::map< CYIString, CYIStringGetProperties () 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 &rPropertyName, const CYIString &rPropertyValue)
 
std::shared_ptr< CYISceneNodeProxyGetSceneNodeProxy () const
 
void SetLayoutConfig (std::unique_ptr< CYILayoutConfig > pLayoutConfig)
 
const CYILayoutConfigGetLayoutConfig (LayoutConfigFetchMode fetchMode=LayoutConfigFetchMode::LazyInstantiate) const
 
CYILayoutConfigGetLayoutConfig (LayoutConfigFetchMode fetchMode=LayoutConfigFetchMode::LazyInstantiate)
 
void SetLayoutState (std::unique_ptr< CYILayoutState > pLayoutState)
 
const CYILayoutStateGetLayoutState () const
 
CYILayoutStateGetLayoutState ()
 
void RequestLayout ()
 
LayoutDirtyFlag GetLayoutDirtyFlag () const
 
virtual void SetLayoutDirtyFlag (LayoutDirtyFlag flag)
 
virtual CYIAbstractCameraSceneNodeFindActiveCamera (const CYISceneNode *pTargetSceneNode=nullptr) const
 
CYIAccessibilityAttributes::Accessible GetAccessible () const
 
void SetAccessible (CYIAccessibilityAttributes::Accessible accessible)
 
const CYIAccessibilityAttributesGetAccessibilityAttributes () const
 
std::unique_ptr< CYIAccessibilityAttributesTakeAccessibilityAttributes ()
 
void SetAccessibilityAttributes (std::unique_ptr< CYIAccessibilityAttributes > pAttributes)
 
const CYIRenderableGetRenderable () 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 &rSignalHandler)
 
virtual ~CYISignalHandler ()
 
CYISignalHandleroperator= (const CYISignalHandler &rSignalHandler)
 
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 &rThreadAffinity)
 
virtual bool IsConnected () const
 
virtual bool IsConnected (const CYISignalBase &rSignal) const
 
void Disconnect (CYISignalBase &rSignal)
 
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 CYISceneNodeGetNodeFromChildren (CYIStringView name)
 
virtual CYISceneNodeGetNodeFromChildren (const int32_t id)
 
virtual CYISceneNodeGetNodeFromChildren (const CYIRuntimeTypeInfo &enforceClassType)
 
CYISceneNodeGetNodeFromChildrenAfterTarget (const CYIRuntimeTypeInfo &enforceClassType, bool *pTargetReached, CYISceneNode *pStartAfterTarget)
 

Static Protected Member Functions

static bool HasAllCaps (const YI_TEXT_DEF &rTextDef)
 
static void UpdateTextForAllCaps (const YI_TEXT_DEF &rTextDef, CYIString &rText)
 

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
 
CYISceneNodem_pParent
 
CYISceneNodem_pDrawParent
 
std::vector< std::unique_ptr< CYISceneNode > > m_children
 
std::vector< CYISceneNode * > m_drawChildren
 
std::map< CYIString, CYIString, std::less<> > m_Properties
 
std::vector< std::shared_ptr< CYIEffect > > m_Effects
 
std::vector< std::unique_ptr< PropertyAnimation > > m_propertyAnimations
 
float m_localOpacity
 
std::unique_ptr< CYITransformm_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< CYIBitmapm_pNPatchBitmap
 
std::shared_ptr< CYIRenderablem_pRenderable
 
- Protected Attributes inherited from CYIEventTarget
std::vector< EventListenerEntry > m_listeners
 
SpecialEventTargetType m_specialTypes
 
std::shared_ptr< CYIEventTargetProxym_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::TypePropertyAnimationComplete
 
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::AccessibleAccessibleStateChanged
 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 rTextDef)
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 rMarkedUpText,
CYITextMarkupParser pMarkupParser = nullptr,
const CYICustomMarkupTagsProvider pExternalTagsProvider = nullptr 
)

Parses the provided marked-up text rMarkedUpText, 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 rText)

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 rText 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 rTextDef,
CYIString rText 
)
staticprotected

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

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