# TextEngine

#### Glyph Spacing

Glyph Spacing is available on [TextBrush](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_brush.html "Output alpha only glyph data. A color may be specified, which is applied to the color channels..."), and LayoutingOptions. This allows a user to correct the spacing between glyphs, by adding a specified number of pixels to the spaces between glyphs.

<div class="contents" id="bkmrk-"><div class="contents"><div class="textblock">---

</div></div></div>#### BitmapFont Engine

BitmapFont Engine is available for usage inside Candera-based applications. A bitmap font is essentially an image file which consists of several characters images and a header that depicts the size and location of each character inside the image. Each bitmap font might contain several fonts - mainly one font face with multiple sizes. One advantage of utilizing bitmap fonts is that the rendering to the screen requires very little resources and since each character is represented as a sub-texture, they can be reused without requiring additional memory on the GPU.

In order to use BitmapFonts, the CMake variable **CANDERA\_FONTENGINE** should be changed to *BitmapFont*.

<div class="contents" id="bkmrk--0"><div class="contents"><div class="textblock"><dl class="note"></dl>  
</div></div></div><p class="callout info">Harbuzz Text Shaper cannot be used with BitmapFont, either ComplexScriptLib or NoShaping should be chosen.</p>

This font engine uses a proprietary format to describe glyph bitmaps and glyph meta info. In order to use a bitmap font, provide an implementation for [Candera::TextRendering::FontStore](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_rendering_1_1_font_store.html "FontStore is an abstract interface to retrieve font data The font store defines unique descriptor id ...").

[Bitmap](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap.html "A 2-dimensional bitmap that can be used as a texture, background or sprite. A bitmap pointing to a va...") fonts require memory mapped assets. So, when the faces are loaded in be sure the storageType is set correctly:

`<a class="el" href="http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_text_rendering_1_1_font_resource_descriptor.html">TextRendering::FontResourceDescriptor</a> descriptor.storageType = <a class="el" href="http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_text_rendering_1_1_font_resource_descriptor.html#aeec8ca3513881b96d67a1af6d5c4c9ddadd7f609d0583effb6a0de5767427464e" title="the font data can be retrieved from a memory location">TextRendering::FontResourceDescriptor::MemoryResource</a>; `

#### Generating Bitmap Fonts

The following steps need to be considered:

<div class="contents" id="bkmrk-install-bitmap-font-"><div class="contents"><div class="textblock">- Install [Bitmap](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_bitmap.html "A 2-dimensional bitmap that can be used as a texture, background or sprite. A bitmap pointing to a va...") Font Generator from [http://www.angelcode.com/products/bmfont/](http://www.angelcode.com/products/bmfont/)

</div></div></div>Open the application. From the Options menu:

<div class="contents" id="bkmrk-choose-font-settings"><div class="contents"><div class="textblock">- Choose Font Settings. Set as needed the settings for "Font", "Add font file", "Size" etc.

- Configure the Export Options. Set "Font descriptor" to "XML" and Textures to "png - Portable Network Graphics"

- "Save bitmap font as ..."

</div></div></div>Convert the resulted XML and PNG files to binary format using the internal tool BmFontCreator using the following command:

<div class="contents" id="bkmrk-bmfontcreator.-exe--"><div class="contents"><div class="textblock">- BmFontCreator. exe -o MyFont32.fbm \*.fnt

</div></div></div><p class="callout info">A bitmap font should be used at its native pixel size. However, they are scalable because of the use of bitmaps, but only scaling down is recommended. In case of up scaling, the visual quality will be reduced. Including separate font sizes for bitmap fonts is possible in order to achieve the best looking results.</p>

<div class="contents" id="bkmrk--1"><div class="contents"><div class="textblock">---

</div></div></div>#### Glyph Substitution

A substitution character may be set within the style with the interface Style::SetDefaultCodepoint. This character is used by the text engine in any of the following situations:

<div class="contents" id="bkmrk-when-a-glyph-is-miss"><div class="contents"><div class="textblock">- when a glyph is missing from the style. i.e. no matching font can provide that glyph. Exception make control character, like newline or LRE.
- when UTF8 buffers contain malformed characters.

---

</div></div></div>#### Character Glyph Mapping

GlyphBitmap now contains information about the position within the text from where the glyphs originated, and the location of the glyph within the font.

<div class="contents" id="bkmrk--2"><div class="contents"><div class="textblock">---

</div></div></div>#### Glyph Order

The order in which glyphs are generated may be controlled by setting a property within the TextRenderContext. See TextRenderContext::GlyphOrder for details. This is most relevant when doing preprocessing. OriginalGlyphOrder is intended for use when intermediate measurements of the text are required, for instance when truncating texts. OrigitnalChunkOrder is more performant then [RenderOrder](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_order.html "Defines the order(sequence) in which nodes are rendered. Collaborates with Renderer. Must cover functional correctness (translucent/transparent objects after opaque/solid objects) as well as optimization-related orderings (sorting by state, defining a background bin for rendering without depth checks). Nodes are assigned to bins; all nodes in an "earlier" bin are rendered before all nodes in a "later" bin. Two default bins are defined and must not be deleted. The opaque bin, which is sorted from front to back (DistanceToCameraOrderCriterion), and the transparent bin, which is sorted from back to front (ReverseDistanceToCameraOrderCriterion). If a Node has no specific assignment to a render order bin, it will be automatically assigned by Candera either to opaque or transparent bin, according to its RenderMode::IsAlphaBlendingEnabled setting."), and is intende for measurements, where the order of the chunk is not important, for instance instance when computing layout rectangles. [RenderOrder](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_render_order.html "Defines the order(sequence) in which nodes are rendered. Collaborates with Renderer. Must cover functional correctness (translucent/transparent objects after opaque/solid objects) as well as optimization-related orderings (sorting by state, defining a background bin for rendering without depth checks). Nodes are assigned to bins; all nodes in an "earlier" bin are rendered before all nodes in a "later" bin. Two default bins are defined and must not be deleted. The opaque bin, which is sorted from front to back (DistanceToCameraOrderCriterion), and the transparent bin, which is sorted from back to front (ReverseDistanceToCameraOrderCriterion). If a Node has no specific assignment to a render order bin, it will be automatically assigned by Candera either to opaque or transparent bin, according to its RenderMode::IsAlphaBlendingEnabled setting.") shall be used when rendering.

<div class="contents" id="bkmrk--3"><div class="contents"><div class="textblock">---

</div></div></div>#### Text Preprocessing

The text engine allows text to be preprocessed by providing utility the class PreprocessingContext. This interface is satisfied by two concrete instances.

<div class="contents" id="bkmrk-minimalpreprocessing"><div class="textblock">- MinimalPreprocessingContext - stores all the information need to be able to render the glyphs.
- MaximalPreprocessingContext - stores all the information available within the text renderer for each glyph. [TextBrush](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_brush.html "Output alpha only glyph data. A color may be specified, which is applied to the color channels...") allows setting PreprocessedText instead of Text, to speed up text processing within the brush.

</div></div>---