You.i Engine
Text

Detailed Description

Text rendering and text input.

You.i Engine provides a very intuitive and flexible mechanism for displaying text in applications. Most of an application's text needs can be authored directly in After Effects in a WYSIWYG (What you see is what you get) manner. This empowers designers to have control over the displaying of text using a familiar editing interface.

Displaying Text

Displaying text in the engine is done using the native text authoring tool in After Effects. Some of After Effects' native text attributes are directly supported by the engine, and some text attributes are supported only through the properties panel.

The following native After Effects text attributes are supported:

Leading specified using After Effects' native text authoring tool is not supported. However, leading can be specified manually using the properties panel.

A list of attributes which are supported through layer comments can be seen in the documentation for CYITextSceneNode.

Rendering Methods

You.i Engine has three methods of rendering text. Each rendering method has its own set of advantages and disadvantages. It is up to the application developer to determine which method of rendering is best suited for a situation. The method of rendering for a specific piece of text can be set by using the class layer comment.

The three rendering methods are:

Atlas Text (CYIAtlasTextSceneNode)

By default, all text displayed will be rendered as atlas text. This method is a commonly used approach to rendering text in GPU accelerated applications. The name comes from its usage of a texture atlas, which is a large texture containing multiple regions which are each used individually as textures.

You.i Engine manages a large texture containing all of the glyphs that it needs to render as atlas text. As new glyphs are needed, they are loaded on demand, and are rendered into the atlas texture. For each character to be rendered, a change in font family, style, or size, will result in a unique glyph being rendered to the atlas texture. A quad, mapped to a glyph in the atlas, is drawn for each glyph rendered to the screen. A quad is simply a quadrilateral rendered by the GPU using four vertices and two triangles.

When rendering atlas text, You.i Engine uses a unique positioning system in order to place every glyph at exact pixel boundaries. In order to facilitate this, the texture atlas also uses nearest-neighbor texture filtering. This system introduces some limitations in the way text can be manipulated in space, and also limits glyph positions to whole numbers when laying out text in order to align with pixel boundaries.

Advantages:

Disadvantages:

Bitmap Text (CYIBitmapTextSceneNode)

Bitmap text is the simplest form of text rendering available in You.i Engine. For each text node using bitmap text, the text content is rendered to a single texture. This texture is then mapped to a quad and is drawn to the screen.

Texture filtering for bitmap text defaults to nearest-neighbor filtering. However, since this form of text rendering uses a single texture for each text node, it is possible to change the texture filtering to use linear interpolation on a per-node basis. This allows an application to support rotating the text as well as moving the text further away from or closer to the camera.

The following code can be used to change the texture filtering on a CYIBitmapTextSceneNode to linear:

CYIBitmapTextSceneNode *pText = YiDynamicCast<CYIBitmapTextSceneNode>(pNode);
if(pText)
{
    pText->SetTextureFilteringMode(CYIAssetTextureBase::Filtering::Linear, CYIAssetTextureBase::Filtering::Linear);
}

This form of text also limits glyph positions to whole number pixel boundaries when laying out text.

Advantages:

Disadvantages:

SDF Text (CYISDFAtlasTextSceneNode)

Signed Distance Field text is an advanced form of text rendering which provides good support for transformations on text. This form of text is similar to atlas text in that it uses a texture atlas to render individual glyphs to quads.

This form of text applies a signed distance field transformation to glyphs before rendering them to a texture atlas. Because this method supports scaling transformations, there is no need to render glyphs at unique sizes to the atlas. When a new glyph is required, it is rendered to the atlas at a specific size, and scaled to the desired font size when drawn to the screen. In some circumstances, this method may use more memory, since glyphs may be rendered to the atlas at a higher resolution than required. This method also uses a separate texture atlas from regular atlas text. The atlas will not be created unless the application renders SDF text.

SDF text requires a proprietary shader in order to render glyphs. The shader has a higher performance impact than the shaders used for the other supported forms of text. Additionally, the shader makes use of pixel shader derivative functions, which are not supported by all GPUs. On platforms using these GPUs, rendering SDF text is not possible.

The following code demonstrates how to query support for SDF text at runtime:

YICapabilities capabilities;
const SYI_CAPS *pDeviceCaps = capabilities.GetDeviceCapabilities();

if(pDeviceCaps->bStandardDerivatives)
{
    // Pixel shader derivatives are supported. SDF text can be used.
}
else
{
    // Pixel shader derivatives are not supported. SDF text can not be used.
}

High quality glyphs can be rendered using this method regardless of the transformation applied. In order to take full advantage of this quality of SDF rendering, text layout is performed with floating point accuracy.

Advantages:

Disadvantages:

Text Layout

Text layout can be controlled entirely from After Effects. After Effects supports two types of text: Point Text, and Paragraph Text. Point text is processed in You.i Engine as a single line of text. No line breaks are applied in this case. When paragraph text is processed, line breaks will be automatically added to the text where it would flow outside of the paragraph box defined in After Effects.

Paragraph text supports an additional text overflow property for defining what happens when the text will not fit in the paragraph box. This allows the developer to optionally add an ellipsis to the text using the properties panel.

Fonts

You.i Engine supports True Type and Open Type fonts (.ttf and .otf). Font files containing a collection of multiple font faces (e.g. Bold, Italic, etc.) are not supported. When previewing a font file, the presence of multiple styles indicates that the file contains multiple faces. Loading a font file containing multiple font faces will result in only the first font face being usable.

The loading of fonts into an application is done automatically for fonts which are required by any loaded layout files. In this case, fonts are loaded on-demand.

When exporting from After Effects, the exporting procedure will automatically search for and add any required font files to the application's asset directory. When opening an After Effects project, a notification will be shown if any fonts used in the project could not be found. After Effects requires the fonts to be installed on the operating system in order to use them. If a required font is not installed and the project is exported, a placeholder font will be exported in its place.

Input

You.i Engine supports text entry through software and physical keyboards. A CYITextEditView can be added to a scene using After Effects to accept keyboard input. Hidden text entry such as for passwords is also supported using CYIPasswordTextEditView.

Some platforms with software keyboards also have support for context specific keyboard layouts (e.g. numerical, phone number, email, etc.). This feature can be leveraged by specifying the input type for the text edit view to use. This can be done through After Effects layer comments with input-type or by setting the input type manually in code.

Rich Text

You.i Engine has support for rich text through the use of a proprietary markup language, and through modifying text in code. All of the text attributes outlined in the Displaying Text section (excluding paragraph alignment), are supported with rich text.

Detailed information on the markup language implemented in You.i Engine and its supported attributes can be found in the CYIYouIMarkupParser documentation.

Classes

struct  YI_GLYPH_DETAILS
 
class  CYIAbstractTextAtlas
 Abstract class for a text atlas. More...
 
class  CYISDFTextAtlas
 Class for a signed distance field text atlas. More...
 
class  CYITextAtlas
 Class for a text atlas. More...
 
class  CYITextEngine
 Class for text rendering. More...
 
class  CYITextLayout
 Base class for abstracting the layout for text. More...
 
class  CYIAtlasTextSceneNode
 A specialized CYITextSceneNode that uses a texture atlas. More...
 
class  CYIBitmapTextSceneNode
 Scene node containing text rendered into a bitmap. More...
 
class  CYISDFAtlasTextSceneNode
 A text scene node which renders text using signed distance fields. More...
 
class  CYITextLabelSceneNode
 This class implements a scene node whose purpose is to display a short text message for debugging purposes. More...
 
class  CYITextSceneNode
 A scene node type that renders text. More...
 
class  CYIPasswordTextEditView
 A CYITextEditView implementation which masks its contents. More...
 
class  CYITextEditView
 Displays text to the user and allows them to edit it. More...