# Fonts and Styles

#### <a class="anchor" id="bkmrk--7"></a>Description

This section contains information about how to use fonts and styles.

#### **Accessing Fonts** 

##### <a class="anchor" id="bkmrk--9"></a>SceneComposer: Import Fonts

For using fonts, first of all the fonts which shall be used need to be imported into the SceneComposer solution.

<div class="contents" id="bkmrk-the-font-will-only-b"><div class="contents"><div class="textblock"><dl class="note"><dt><p class="callout info">The font will only be available in the finally generated asset, if:   
- it is either used in any scene (as part of a style which is used in a widget style property for example)   
- or the "Always include in asset" flag is enabled in the font resource.</p>

</dt></dl></div></div></div>**See also:**

<div class="contents" id="bkmrk-import-fonts-in-scen"><div class="contents"><div class="contents"><div class="textblock">- <span style="color: rgb(230, 126, 35);">[How to Import Resources](https://doc316en.candera.eu/books/import-of-resources/page/how-to-import-resources)</span> in SceneComposer User Manual

</div></div></div></div>##### <a class="anchor" id="bkmrk--10"></a>Initializing FontEngine

Next, the application needs to create a <span style="color: rgb(230, 126, 35);">[Candera::TextRendering::FontEngine](http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_text_rendering_1_1_font_engine.html)</span> instance and initialize it for using the <span style="color: rgb(230, 126, 35);">[Candera::AssetFontStore](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_asset_font_store.html "implements a font store for the asset library this is the default font store Candera will use to retr...")</span>. AssetFontStore will access the font part of the loaded asset and provide it to the TextEngine.

```
    static AssetFontStore s_fontStore;

    result = result &
&
<a class="code" href="http://dev.doc.cgistudio.at/APILINK/struct_candera_1_1_text_rendering_1_1_font_engine.html#a9a4b6b6f60139c0a62683ef1f60f55fd">Candera::TextRendering::FontEngine::Instance</a>().Init(&
s_fontStore);

```

<div class="contents" id="bkmrk-"><div class="contents"><div class="textblock"><div class="fragment">  
</div></div></div></div>##### <a class="anchor" id="bkmrk--11"></a>Using a Font

The easiest way to use a font is to setup the font as part of a <span style="color: rgb(230, 126, 35);">[Candera::TextRendering::Style](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_rendering_1_1_style.html "Defines a text style.")</span> and use the style as a widget property within SceneComposer. This allows to specify the FontFamily and the FontSize via SceneComposer GUI. FontSize has to be specified in pixel size (see <span style="color: rgb(230, 126, 35);">[Font Metrics and Text Sizes](https://doc316en.candera.eu/link/480#bkmrk-font-metrics-and-tex)</span>). In case the application needs to switch the font dynamically, at runtime, setup the font and create a style:

```
    Font font;

    font.Setup("openSans", 20);

    m_style = <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___c_o_u_r_i_e_r___v_i_s_u_a_l_i_z_a_t_i_o_n.html#ggaf0e93dc4242f607c3c8d13dafd036af9aaabfa5309af24986d3111a092449f857">SharedStyle::Create</a>();

    m_style->
SetDefaultFont(font);

```

<div class="contents" id="bkmrk--0"><div class="contents"><div class="textblock"><div class="fragment">  
</div></div></div></div>##### <a class="anchor" id="bkmrk--12"></a>Access to AssetFontStore

Include FontFaceName and FontFaceSize Property in the header file of the widget.

```
// Add Property
            CdaProperty(FontFaceName, const Candera::Char*, GetFontName, SetFontName)
                CdaDescription("Font Face <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behaviors_mixed_reality.html#gga70813433b87d1347efaf56d755a186c1aa161dba378f926eef1e116dd38c4b6c6">Name</a> for the text (used only if \"Use <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behaviors_control.html#ggae7abc816df647d0ecbc280480fefb788a595c025970839adf97b121009ea58dfc">Text</a> Font Property\" is disabled).")
                CdaCategory("Accessing Fonts from FontEngine")
            <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___meta_info.html#ga119bef57449bd05d8b3c40d7d514e375">CdaPropertyEnd</a>()

            CdaProperty(FontFaceSize, Candera::UInt16, GetFontSize, SetFontSize)
                CdaDescription("Font Face Size for the text (used only if \"Use <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___behaviors_control.html#ggae7abc816df647d0ecbc280480fefb788a595c025970839adf97b121009ea58dfc">Text</a> Font Property\" is disabled).")
                CdaCategory("Accessing Fonts from FontEngine")
            <a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___meta_info.html#ga119bef57449bd05d8b3c40d7d514e375">CdaPropertyEnd</a>()
// end add Property
```

<div class="contents" id="bkmrk-the-fontfacename-pro"><div class="contents"><div class="textblock"><dl class="warning"><dd><p class="callout warning">The FontFaceName property must be set with a valid [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") path. Keep in mind that, unlike paths generated by the Font dialog where the; the "/" character, the [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") paths use "#" as delimiter.</p>

</dd></dl></div></div></div>Also, do not forget to initialize member variables in the constructor, otherw; e SceneComposer will not be able to work with the widget.

```
SimpleTextWidget::SimpleTextWidget() :
    m_text(0),
    m_style(SharedStyle::<a class="code" href="http://dev.doc.cgistudio.at/APILINK/group___c_o_u_r_i_e_r___v_i_s_u_a_l_i_z_a_t_i_o_n.html#ggaf0e93dc4242f607c3c8d13dafd036af9aaabfa5309af24986d3111a092449f857">Create</a>()),
    m_color(),
    m_shader(0),
    m_fontName(0),
    m_fontSize(12),
    m_bb(0),
    m_bitmap(0),
    m_bitmapPixels(0),
    m_defautScaleVector(1.0,1.0,1.0),
    m_useTextFont(true),
    m_;
UpdateRequired(true),
    mTextStartPos(0, 0)
{
}
```

Setup the font as described below.

```
        static Font f;
        if (f.Setup(m_fontName, static_cast<Candera::Int16>(m_fontSize))) {
            m_font = f;
        }
```

And update the style used for rendering:

```
    m_style->SetDefaultFont(m_font);
```

##### <a class="anchor" id="bkmrk--13"></a>AssetFontStore Load Strategies

AssetFontStore supports two font load strategies:

<div class="contents" id="bkmrk-preloadstrategy%3A-ent"><div class="contents"><div class="textblock">- <span style="color: rgb(230, 126, 35);">[PreloadStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_asset_font_store_1_1_load_strategy_selector.html#a3c06cdd0709312d8b0ac60035c9a3b62aad010b9a2098e4e40ff1f0be8f31ba4b)</span>: entire fonts are loaded into memory once and font data; accessed from there by Text <span style="color: rgb(0, 0, 0);">Engine.</span>
- <span style="color: rgb(230, 126, 35);">[OnRequestLoadStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_asset_font_store_1_1_load_strategy_selector.html#a3c06cdd0709312d8b0ac60035c9a3b62abddf5927381d24532b5a902fda7d33f3)</span>: small font portions are streamed directly from the asset repository when Freetype (or indirectly Harfbuzz) needs them.

</div></div></div>Use <span style="color: rgb(230, 126, 35);">[SetDefaultFontLoadStrategy](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_default_load_strategy_selector.html#a340dda8ac0dfb937a3d77d68817bfd48)</span> to select one of these load strategies.

Use <span style="color: rgb(230, 126, 35);">[SetDefaultFontLoadStrategyExceptionL; t](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_default_load_strategy_selector.html#ac9e45f0d804d98677032b463b50b3513)</span> to exclude a l; t of fonts from the selected font load strategy.

Example:

```
    // Load fonts with OnRequestLoadStrategy
    selector.SetDefaultFontLoadStrategy(<a class="code" href="http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_asset_font_store_1_1_load_strategy_selector.html#a3c06cdd0709312d8b0ac60035c9a3b62abddf5927381d24532b5a902fda7d33f3" title="Do not load anything in memory, but read/copy data into smaller temporary buffers as requested by Fre...">Candera::AssetFontStore::LoadStrategySelector::OnRequestLoadStrategy</a>);
    // "Bitstream Vera Sans" font shall be loaded with PreloadStrategy:
    const Char* g_fontName[2] = { "ConstructionKit##ConstructionKit#Resources#Fonts#Bitstream Vera Sans", 0 };
    selector.SetDefaultFontLoadStrategyExceptionL;
t(g_fontName);
    fontStore.SetLoadStrategySelector(&selector);
```

<div class="contents" id="bkmrk-courier-applications"><div class="textblock"><dl class="note"><dd><p class="callout info"><span style="color: rgb(230, 126, 35);">[Courier](http://dev.doc.cgistudio.at/APILINK/namespace_courier.html)</span> applications can use <span style="color: rgb(230, 126, 35);">[Courier::ViewHandler::SetFontStoreProviderCallback](http://dev.doc.cgistudio.at/APILINK/class_courier_1_1_view_handler.html#a7747f74f80b57fd376b13f942d927009)</span> to provide specific settings for the <span style="color: rgb(230, 126, 35);">[Candera::AssetFontStore](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_asset_font_store.html "implements a font store for the asset library this is the default font store Candera will use to retr...")</span> in use.</p>

</dd></dl></div></div>#### **Text Style: A Composition of Fonts** 

##### <a class="anchor" id="bkmrk--14"></a>Text Style: Introduction

A Style can be seen as a composition of fonts.

Basically for a range of glyphs a proper font can be specified (also called *style entry*). Beside the style entries a style also cons; ts of a default font and a base style.

<div class="contents" id="bkmrk-the-style-entries-ar"><div class="contents"><div class="textblock">- The style entries are parsed from the first to the last style entry until a code point range that contains the input code point; found.
- All glyphs which do not match to one of the specified *style entry* range are rendered with the default font.
- The same parsing order; applied to code points which match to a range of a style entry, but the font does not contain a glyph for th; code point
- Each style can use another style as base style, which allows an arbitrary complex composition of fonts.

</div></div></div>The **TextRenderingSolution** provided in the content folder of *cgi\_studio\_player* gives an example how text features can be applied in SceneComposer.

<div class="contents" id="bkmrk-see-also%3A-text-style"><div class="textblock"><dl class="see"><dt>**See also:**</dt><dd>- <span style="color: rgb(230, 126, 35);">[Text Style Palette](https://doc316en.candera.eu/books/solution-handling/page/text-style-palette "Text Style Palette")</span> in SceneComposer User Manual
- [Candera::TextRendering::Style](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_rendering_1_1_style.html "Defines a text style.") in <span style="color: rgb(230, 126, 35);">[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]")</span> API

</dd></dl></div></div>#### **Text Style: Example** 

##### <a class="anchor" id="bkmrk--15"></a>Example

Use **TextRenderingSolution** provided in the content folder of *cgi\_studio\_player* to see how text features can be applied in SceneComposer.

<div drawio-diagram="2221"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1677044019.png" alt=""/></div>

<div class="contents" id="bkmrk--3"><div class="contents"><div class="textblock">  
</div></div></div>  
Select *Scene2D\_StyleExample* of the solution, which gives just a brief overview of text features and how they look like. It cons; ts of

<div class="contents" id="bkmrk-a-candera%3A%3Atextnode2"><div class="contents"><div class="textblock">- a <span style="color: rgb(230, 126, 35);">[Candera::TextNode2D](http://dev.doc.cgistudio.at/APILINK/class_candera_1_1_text_node2_d.html "TextNode2D is a RenderNode that renders text using the attached BitmapBrush effect.")</span>.
- Fonts for the text node are defined in a style *Mystyle*.

</div></div></div>Lets consider the configured style *MyStyle* set in the TextNode2D's style property:

<div class="contents" id="bkmrk-the-default-font-pro"><div class="contents"><div class="textblock">- The **Default Font** property is set with predefined *DefaultFont* (Vera size 20)
- No **Base Style**, therefore for this field *Empty*, is defined

</div></div></div>Expanding the Children panel shows the defined style entries. The example style consists of three style entries.

<div class="contents" id="bkmrk-entry-0-defines-the-"><div class="contents"><div class="textblock">- **Entry 0** defines the font *BigLetter* (Comic size 60) for all glyphs in the code point range from 65 to 90. These upper and lower bounds represent the glyph range 'A' (65) - 'Z' (90) in decimal representation. In the example therefore all upper case letters are rendered with font *BigLetter*.
- **Entry 1** defines font *BigLetter* for numbers '0'(48) - '9'(57).
- **Entry 2** defines font *Korean* (UnBom size 40) for Korean glyphs. Code points for asian glyphs are in range 44032 - 55215 (in decimal representation). So using styles, glyphs from different cultures can be rendered without changing the font/style settings.

</div></div></div>In case of this example all lower case letters do not have a proper style entry and the default font is taken to render.

<div class="contents" id="bkmrk-if-the-code-ranges-o"><div class="textblock"><dl class="note"><dt></dt><dd><p class="callout info">If the code ranges of different style entries overlap, the style entry with the higher number has priority (e.g. font in entry 2 has higher priority than font in entry 1).</p>

</dd></dl></div></div>#### **Bitmap Font Engine**   


##### <a class="anchor" id="bkmrk--17"></a>Overview

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.

##### <a class="anchor" id="bkmrk--18"></a>CMake configuration

In order to be able to use the bitmap font engine the <span style="color: rgb(230, 126, 35);">[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]")</span> CMake project should be configured as follows:

<div class="contents" id="bkmrk-candera_fontengine-s"><div class="contents"><div class="textblock">- CANDERA\_FONTENGINE should be set to *"Bitmap Font"*
- CANDERA\_BITMAPFONT\_FACE\_SIZE\_COUNT\_MAX represents the number of font sizes supported. Default value is set to 6.
- CANDERA\_BITMAPFONT\_GLYPH\_CACHE\_SIZE represents the size of the buffer to cache glyph bitmaps. By default the value is set to 24\*24\*100.

</div></div></div><div class="contents" id="bkmrk-candera_textshaper-s"><div class="contents"><div class="textblock"><dl class="note"><dd><p class="callout info">CANDERA\_TEXTSHAPER should be set to *"NoShaping"* or *"ComplexScriptLib"* because Harbuzz Text Shaper cannot be used with BitmapFont.</p>

</dd></dl></div></div></div>##### <a class="anchor" id="bkmrk--19"></a>Font Setup

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 <span style="color: rgb(230, 126, 35);">[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 ...")</span>.

Bitmap fonts require memory mapped assets. So, when the faces are loaded in be sure the storageType is set correctly:

```
    TextRendering::FontResourceDescriptor descriptor.storageType = TextRendering::FontResourceDescriptor::MemoryResource;
```

##### <a class="anchor" id="bkmrk--20"></a>Generating Bitmap Fonts

The following steps need to be considered:

1\. Install Bitmap Font Generator from [http://www.angelcode.com/products/bmfont](http://www.angelcode.com/products/bmfont)

2\. 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"*

</div></div></div>3\. From the right panel of the main window select the needed subsets of glyphs.

4\. Export the font by choosing *"Save bitmap font as ..."* from the **Options** menu.

Please see <span style="color: rgb(230, 126, 35);">[Import Fonts](https://doc316en.candera.eu/link/1101#bkmrk-image%2C-font%2C-shader%2C-1)</span> for details about the importing of bitmap fonts in SceneComposer.

<div class="contents" id="bkmrk-a-bitmap-font-should"><div class="textblock"><dl class="note"><dd><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>

</dd></dl></div></div>