# Integration of Monotype

This section provides an overview of the Monotype integration.

The current integration is a hardwired solution. Therefore, the choice of which engine shall be used, has to be made at precompile-time (CMake decision).

The following features have been integrated:

<div class="contents" id="bkmrk-font-engine%3A-itype"><div class="contents"><div class="textblock">- Font engine: iType

</div></div></div>#### <a class="anchor" id="bkmrk-"></a>The font engine: iType

iType is a font engine which main purpose is fast and qualitative rasterization of fonts.

<p class="callout info">To see, which version of iType is currently supported, please have a look at the <span style="color: rgb(230,126,35);">[\[3rd Party Software section\]](https://doc316en.candera.eu/books/getting-started/page/cgi-studio-components#bkmrk-cgi-studio-3psw)</span>.</p>

There are two different approaches to integrate the third party code iType into CGIStudio:

<div class="contents" id="bkmrk-adding-prebuilt-libr"><div class="contents"><div class="textblock">- adding prebuilt libraries
- add the third party code into the build process

</div></div></div>CGIStudio supports both by CMake settings.

Monotype/iType has a special porting API with which target and OS specifics can be overridden.

CGIStudio provides a single solution for all targets. For this, the framework links the API to the device and operating system layers.

It is also possible to use an own customized port instead of the CGIStudio solution.

#### <a class="anchor" id="bkmrk--0"></a>Cache support

The iType integration concentrates on the most performant cache types: BitmapCache and GlyphAtlas. Therefore, only these two cache types are fully supported.

#### <a class="anchor" id="bkmrk--1"></a>Overview: CMake settings

Currently CMake supports general iType integration flags to include Monotype.

To switch to the font engine the following CMake flag has to be set:

<div class="contents" id="bkmrk-flag-value-candera_f"><div class="contents"><div class="textblock"><table class="doxtable" style="width: 41.8519%;"><tbody><tr><th style="width: 56.5298%;">**Flag**</th><th style="width: 43.4702%;">**Value**</th></tr><tr><td style="width: 56.5298%;">CANDERA\_FONTENGINE</td><td style="width: 43.4702%;">Monotype</td></tr></tbody></table>

</div></div></div>If HarfBuzz is selected as the current TextShaper, the flag CANDERA\_TEXTSHAPER automatically will change to WorldType-Shaper. Shaping can also be disabled.

<div class="contents" id="bkmrk-harfbuzz-requires-fr"><div class="contents"><div class="textblock"><dl class="note"><dt></dt><dd><p class="callout info">HarfBuzz requires Freetype and is not available for iType.</p>

</dd></dl></div></div></div>This flag is called Monotype to switch to the available Monotype engines. The concrete font engine will be iType.

By enabling Monotype, several CMake flags become available.

The flag MONOTYPE\_USE\_BINARIES can be used to switch between the different building modes.

They have their own flags which will be described within the corresponding build process description.

#### <a class="anchor" id="bkmrk--2"></a>Build process: iType as source code

For this mode, MONOTYPE\_USE\_BINARIES has to be disabled.

<div class="contents" id="bkmrk-onotype_font_engine_"><div class="contents"><div class="textblock">- ONOTYPE\_FONT\_ENGINE\_SRC\_PATH - This path defines the location where to find the source code for iType. By default this will be cgi\_studio\_3psw/src/Monotype/iType and the folder structure may look like the following:  
    <div drawio-diagram="1423"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676532389.png" alt="drawing-4-1676532389.png"/></div>
    
      
      
    The FileList.txt which defines all the files should contain the following three Lists: 
    - - MONOTYPE\_PUBLIC\_HEADERS
        - MONOTYPE\_PRIVATE\_HEADERS
        - MONOTYPE\_SOURCES
    
    <dl class="note"><dt></dt><dd><p class="callout info">It does not matter how the source code is distributed on these lists. Only the names should be in use</p>
    
    </dd></dl>
- MONOTYPE\_FEATSTD\_PORT\_ENABLED - This flag toggles the port API implementation between a CGIStudio version and the default win32\_lib including the settings which are required for Candera. The win32\_lib represents a default implementation of the framework, separated from any Candera relations. This enables an easy possibility to build iType in a separated environment and link it to Candera.
- MONOTYPE\_FONT\_ENGINE\_PORT\_PATH - This path is directly links to the port API which shall be used for the build. By default it links to the default location of the default CGIStudio implementation: cgi\_studio\_3psw/src/Monotype/iType/source/port/CGIStudio However, this can be changed to different implementations, too. If MONOTYPE\_FEATSTD\_PORT\_ENABLED is false, this will link to the win32\_lib definition.

</div></div></div>#### <a class="anchor" id="bkmrk--4"></a>Build process iType as prebuilt library

For this mode, MONOTYPE\_USE\_BINARIES has to be enabled.

In general using the prebuilt library is similar to the source code version.

The flags MONOTYPE\_FEATSTD\_PORT\_ENABLED, MONOTYPE\_FONT\_ENGINE\_PORT\_PATH and MONOTYPE\_FONT\_ENGINE\_SRC\_PATH are equal in usage as in the source code version. The only difference is, that the prebuilt library only requires header files.

The port files and header have to match with the build settings of the prebuilt library.

MONOTYPE\_ITYPE\_LIBRARY\_FILEPATH is the path to the prebuilt library. And has to be defined by the user.

#### Monotype – Prepopulated font engine cache

This feature shall be used to load font bitmap data into the font engine cache.

##### CMAKE Configuration

1. Set CANDERA -&gt; CANDERA\_FONTENGINE to Monotype
2. Configure
3. Check MONOTYPE -&gt; MONOTYPE\_PREPOPULATED\_CACHE\_ENABLED

##### Usage

1. Include the previously created cache dump header file.
2. Include the “MtInclude” header  
      
    \#include &lt;Candera/TextEngine/Monotype/MtInclude.h&gt;
3. Create an instance of a font that is present in the asset. The name of the font must match the “Candera Name” property of the font resource in the scene composer. The font size parameter of the Setup call is irrelevant.  
      
     Candera::TextRendering::Font font;  
     font.Setup("ConstructionKit##ConstructionKit#Resources#Fonts#Open Sans Light", 20);
4. Call FontEngine::InitPrepopulatedCache with the font and a reference to the utilCache variable from the cache dump file.  
      
    Candera::TextRendering::FontEngine::Instance().InitPrepopulatedCache(font, &amp;utilCache);

##### Possible Pitfalls

- The cache should be prepopulated during startup of the application. Thus, the above methods shall be called when the Courier::StartupMsg is received.
- The “faceName” property of the Font::Setup call must match the “Candera Name” property of the font in the composer.
- The font size used when displaying the text, e.g. with a TextNode, must match the font size used when generating the cache dump file.
- While generating the cache dump file, the glyph maps must be retrieved as GRAYMAP’s by calling  
    map = FS\_get\_glyphmap(FS\_state\_ptr, glyphIDs\[i\], FS\_MAP\_GRAYMAP8);
- When generating the cache dump file, fs\_config.h should match the configuration in cgi\_studio\_3psw\\src\\Monotype\\iType\\source\\common\\fs\_config.h