Tip / Sign in to post questions, reply, level up, and achieve exciting badges. Know more

cross mob

TRAVEO™ T2G MCU: Font rendering on T2G-Cluster device - KBA236089

TRAVEO™ T2G MCU: Font rendering on T2G-Cluster device - KBA236089

Community Manager
Community Manager
Community Manager
1000 replies posted First like given 750 replies posted

Version: **

Rendering text on a display is a common task. For example, buttons can be labeled, or you might want to inform the user about the current status or other events happening.

The TRAVEO™ T2G-Cluster device with its graphics unit and driver supports font rendering in various ways by utilizing the BlitEngine or the DrawingEngine. This KBA explains font rendering in general, provides example code usable with the graphics driver and general guidelines.

1 Rendering fonts

To render fonts on the screen, the graphical description of every symbol must be available. This is called a glyph.

Glyphs can be stored in different file formats like the TrueTypeFont (.ttf). Here, the information is stored as vector drawings by specifying path coordinates and path commands. As an alternative, glyphs can also be stored as a bitmap. This contains pixel information. A comparison between both is made in Table 1.

Table 1  Comparison between .ttf and bitmap approach




Information stored

As vector drawings

As pixel information

Driver Usage

Mostly DrawingEngine








It is difficult to give a definitive statement about the performance, because this highly depends on your application. In general, using the .ttf approach utilizes the DrawingEngine, which works in Image-Based-Operation (IBO) mode and has to do additional calculations to rasterize the image and therefore is most likely slower.

Because fonts often have to be scaled to various sizes, vector fonts are mainly used. If you have a simple application and do not want to have the overhead of vector drawings, a bitmap solution is good enough.

The T2G-Cluster devices are capable of both approaches and are explained further.

2  Using DrawingEngine via FreeType library

The FreeType library is a software library available for free to render fonts that are described by vector drawings in file formats like .ttf.

Figure 1 shows an example of the letters a, b, and c:

Figure 1   The letters a, b and c as vector drawings, in which the path information (nodes) are visible.

Here, a letter consists of a path of nodes containing various lines such as straight ones or beziér curves. This information is stored for each glyph in the .ttf file, which then can be interpreted by the TRAVEO™ T2G-Cluster device DrawingEngine to render it. Advantage of this approach is the scaling of the font. Because everything is described with path data, resizing of the font results in sharp text.

 There are some hardware limitations for this approach such as no intersecting outlines are allowed. For details, see the user guide of the graphics driver, which is in the root folder of your driver installation.

2.1  Importing .ttf file to T2G graphics driver

To use the .ttf file in the graphics driver, it first has to be converted into a suitable header file. For this, the Bin2Text.exe tool provided in the graphics driver is installed at 08_tool/basic_graphics/bin/windows. This application is used via command line. To convert a file called font.ttf into a header file called font_ttf.h, use the command as per Code Listing 1.

Code Listing 1     

001:     Bin2Text.exe font.ttf font_ttf.h

Assuming the working directory is the same as the application and font.ttf.

The created header file must be included into your project. If you use a default graphics driver installation, the FreeType library is already available and the utility library provides ease-to-use functions for it. Only thing left to do is telling the linker to use these libraries. Assuming your project is located in the same folder as the examples of the graphics driver, you are using the GHS-toolchain and a 6M-board, you have to specify the path of the FreeType library in tools/ghs/tvii2d6m/tviic2d6m_common.gpj using the command line in Code Listing 2.

Code Listing 2  

001:     macro FT_REL_PATH=..\..\..\..\..\..\09_externals\freetype

Using the command lines in Code Listing 3, invoke GHS to include the files in tools/ghs/options_cm7.opt.

Code Listing 3  

001:     -I$(UTIL_REL_PATH)\utfreetype\include
002:     -I$(FT_REL_PATH)\include

In tools/ghs/_gpj/program.gpj, you have to specify that you want to link the FreeType library with the following command line in Code Listing 4.

Code Listing 4    

001:     {!streq(CPU_NAME, "cm0plus")} -lfreetype_$(CPU_NAME)

Finally, specify where to put the FreeType library in memory by
modifying tools/ghs/tviic2d6m/linker_directives.ld. For example, put the FreeType library before the .cygfx_res_section (if available), but feel free to adjust this to your needs. The directives are as following:

Code Listing 5        

001:     .cygfx_text_freetype               

Now you should be able to compile and link your project with the FreeType library. If you use another toolchain or board, please adapt the steps accordingly.

If all these steps are done, one can use the utility library by including ut_freetype.h to create a FreeType context, open the font and draw text using the command line in Code Listing 6.

Code Listing 6   

001:     FT_CONTEXT_CONTAINER ft_ctx;
002:     utFtOpen(&ft_ctx, ctx, (const CYGFX_CHAR*) font_ttf, sizeof(font_ttf), 24);    // font_ttf from Bin2Text
003:     CyGfx_BeSetSurfAttribute(ctx, CYGFX_BE_TARGET_SRC, CYGFX_BE_SURF_ATTR_COLOR, CYGFX_SM_COLOR_TO_RGBA(255, 255, 255, 255));     // Color of text
004:     utFtTextOut(&ft_ctx, 0, 0, L"Hello, World!");
005:     // …
006:     utFtClose(&ft_ctx);    // close if font_ttf will not be used again

Note that the DrawingEngine is used with these operations. Therefore, you have to create a path buffer and an alpha buffer beforehand. The size of latter depends on how much text you want to be able to draw at once.

If you are using a coordinate system with the origin in the top-left corner, the text will be most likely mirrored on your display. To fix this, you can apply a mirror matrix transformation via utility function using the command line from Code Listing 7.

Code Listing 7 

001:     Mat3x2 mat_rot;
002:     utMat3x2LoadIdentity(mat_rot);
003:     mat_rot[3] = -1;       // need to mirror on x-axis
004:     utFtRotation(&ft_ctx, mat_rot);

Even though the function is called utFtRotation(), you can supply a mirror matrix. Pay attention that when calling utFtTextOut(), the provided coordinates references the bottom left point of the text, therefore you might want to set the parameter for the y-coordinate to the height of the text.

There are other functions available in the utility library for the FreeType library. For more details, see the user guide.

3 Using Bitmaps

To use the bitmap approach, you will need a surface of your glyphs. This surface can be created by exporting an image file via the ResourceGenerator. This image should be a fixed size 16x16 grid including each glyph in its respective ASCII order as shown in Figure 2.




Figure 2    A bitmap consisting of a 16x16 grid of glyphs. Note the ASCII order (for example letter A is at the 65th position)

Instead of manually handling the blitting of the font surface on your desired surface, the utility library provides functionality to do so. This is done by creating a utility context. Here you can also specify the character size and space if your grid is not of fixed size. This is done by utSetCharacterSize() and utSetCharacterSpace().

Assuming further that a bitmap header-file was created and is named courier_12. It can be loaded as a surface and set as a font in the utility library using command lines from Code Listing 8

Code Listing 8 

001:     UTIL_CONTEXT utCtx;
002:     CYGFX_SURFACE surf_font = NULL;
03:     utSmGenSurfaceObjects(1, &surf_font);
04:     utSurfLoadBitmap(surf_font, courier_12, CYGFX_FALSE);
005:     utSetFont(&utCtx, surf_font);

To draw text, you have to specify the target surface of your utility context with utTarget(). When done, drawing text is done by using command line from Code Listing 9.

Coding Listing 9

001:     utTextOut(&utCtx, 0, 0, "Hello, World!");

Note that this approach can be faster but has the disadvantage of bad scaling. If your font-bitmap is of low resolution and you want to draw large letters, you will get a blurry result.