Difference between revisions of "Font rendering"

From uGFX Wiki
Jump to: navigation, search
(→‎Fonts)
(→‎Anti-Aliasing)
 
(40 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
µGFX comes with a built-in support of [https://code.google.com/p/mcufont/ mcufont]. The author of the mcufont project provides a re-licensed version of his works to the µGFX projects.
+
== Features ==
−
 
+
−
== Feature ==
+
 
The µGFX font rendering engine provides the following features:
 
The µGFX font rendering engine provides the following features:
−
* unicode
 
−
* anti-aliasing
 
−
* kerning
 
−
* .ttf and .bdf support
 
  
 +
=== Word-Wrapping ===
 +
The word wrapping feature can be enabled by setting <code>GDISP_NEED_TEXT_WORDWRAP</code> to <code>TRUE</code>.
 +
 +
Word wrapping only has an effect when using <code>gdispDrawStringBox()</code> or <code>gdispFillStringBox()</code>. When the word wrapping feature is not enabled the string will simply be cut-off at the border of the specified box.
 +
 +
=== Unicode ===
 +
[http://en.wikipedia.org/wiki/Unicode Unicode] support can be enabled by setting <code>GDISP_NEED_TEXT_UTF8</code> to <code>TRUE</code>.
 +
 +
Unicode support allows to display fonts of many different languages such as English, French, German, Russian (Cyrillic), Chinese, Japanese and so on.
 
For information about cyrillic font support, see [[Cyrillic]].
 
For information about cyrillic font support, see [[Cyrillic]].
 +
 +
=== Anti-Aliasing ===
 +
To use the anti-aliasing font feature, the following three conditions have to be fulfilled:
 +
# Using an anti-aliased font
 +
# <code>GDISP_NEED_ANTIALIAS</code> needs to be set to <code>TRUE</code>
 +
# Either have <code>GDISP_NEED_PIXELREAD</code> set to <code>TRUE</code> or using one of the [[Drawing#Text|text drawing functions]] that have a background color parameter.
 +
 +
Note that you can use normal (non anti-aliased) fonts along with anti-aliased ones without any problems.
 +
 +
=== Kerning ===
 +
[http://en.wikipedia.org/wiki/Kerning Kerning] support can be enabled by setting <code>GDISP_NEED_TEXT_KERNING</code> to <code>TRUE</code>.
 +
 +
=== TrueType-Font support ===
 +
Any [http://en.wikipedia.org/wiki/TrueType TrueType-Font] available in a *.ttf or a *.bdf file format can be used in uGFX. See [[Font_rendering#Adding Fonts|Adding Fonts]].
  
 
== Fonts ==
 
== Fonts ==
−
Every font that's available in a .ttf or .bdf format can be displayed through µGFX. However, we added a bunch of fonts in different sizes and versions which should cover most use cases:
+
Every font that's available in a .ttf or .bdf format can be displayed through µGFX. However, we already added a bunch of fonts in different sizes and versions which should cover most use cases. Use the '''Font name''' as the parameter of the <code>gdispOpenFont()</code> routine.
−
* UI1
+
{| class="wikitable"
−
* UI2
+
! scope="col"|Font
−
* DejaVu Sans 10 (normal and anti-aliased)
+
! scope="col"|Font name
−
* DejaVu Sans 12 (normal and anti-aliased)
+
|-
−
* DejaVu Sans 16 (normal and anti-aliased)
+
|DejaVu Sans 10
−
* DjeaVu Sans 24 (normal and anti-aliased)
+
|DejaVuSans10
−
* DejaVu Sans 32 (normal and anti-aliased)
+
|-
−
* DejaVu Sans Bold
+
|DejaVu Sans 12
−
* Fixed 5x8
+
|DejaVuSans12
−
* Fixed 7x14
+
|-
−
* Fixed 10x20
+
|DejaVu Sans 12 Bold
 +
|DejaVuSansBold12
 +
|-
 +
|DejaVu Sans 12 Anti-Aliased
 +
|DejaVuSans12_aa
 +
|-
 +
|DejaVu Sans 12 Anti-Aliased Bold
 +
|DejaVuSansBold12_aa
 +
|-
 +
|DejaVu Sans 16
 +
|DejaVuSans16
 +
|-
 +
|DejaVu Sans 16 Anti-Aliased
 +
|DejaVuSans16_aa
 +
|-
 +
|DejaVu Sans 20
 +
|DejaVuSans20
 +
|-
 +
|DejaVu Sans 20 Anti-Aliased
 +
|DejaVuSans20_aa
 +
|-
 +
|DejaVu Sans 24
 +
|DejaVuSans24
 +
|-
 +
|DejaVu Sans 24 Anti-Aliased
 +
|DejaVuSans24_aa
 +
|-
 +
|DejaVu Sans 32
 +
|DejaVuSans32
 +
|-
 +
|DejaVu Sans 32 Anti-Aliased
 +
|DejaVuSans32_aa
 +
|-
 +
|Fixed 10x20
 +
|fixed_10x20
 +
|-
 +
|Fixed 7x14
 +
|fixed_7x14
 +
|-
 +
|Fixed 5x8
 +
|fixed_5x8
 +
|-
 +
|UI1
 +
|UI1
 +
|-
 +
|UI1 Double
 +
|UI1 Double
 +
|-
 +
|UI1 Narrow
 +
|UI1 Narrow
 +
|-
 +
|UI2
 +
|UI2
 +
|-
 +
|UI2 Double
 +
|UI2 Double
 +
|-
 +
|UI2 Narrow
 +
|UI2 Narrow
 +
|-
 +
|Large numbers
 +
|LargeNumbers
 +
|}
 
Note that each of these fonts has to be enabled in your [[Configuration|configuration file]].
 
Note that each of these fonts has to be enabled in your [[Configuration|configuration file]].
  
Line 28: Line 107:
  
 
== Usage ==
 
== Usage ==
−
Before you can use an added font, you first have to open it by calling <code>gdispOpenFont()</code>. Opening a font prepares the memory resources and encodes the font as required.
+
Before you can use a font, you first have to open it by calling <code>gdispOpenFont()</code>.
 
<syntaxhighlight lang=c>
 
<syntaxhighlight lang=c>
−
font_t font = gdispOpenFont("DejaVuSans32_aa");
+
gFont font = gdispOpenFont("DejaVuSans32_aa");
 
</syntaxhighlight>
 
</syntaxhighlight>
−
You may call <code>gdispCloseFont()</code> to release any allocated memory resources if you don't need a font any longer:
+
'''''Note:''' When the font name specified could not be found, the last enabled font in the [[Configuration|configuration file]] will be used.''
 +
 
 +
You should call <code>gdispCloseFont()</code> to release any allocated resources if you don't need a font any longer:
 
<syntaxhighlight lang=c>
 
<syntaxhighlight lang=c>
 
gdispCloseFont(font);
 
gdispCloseFont(font);
 
</syntaxhighlight>
 
</syntaxhighlight>
−
After opening a font, the font variable can now be passed to any API call that takes a font parameter. You may read through the [[GDISP#API_Reference|API reference]] to get a list of all font rendering routines. However, you might want to consider using the [[Label|label widget]] to display text boxes.
+
After opening a font, the font variable can now be passed to any API call that takes a font parameter. You may start by reading through the basic [[Drawing#Text|GDISP text drawing routines]] before you take a look at the different [[GWIN|GWIN]] system.
  
 
== Adding fonts ==
 
== Adding fonts ==
Line 45: Line 126:
  
 
=== 2. Convert the font ===
 
=== 2. Convert the font ===
−
The next step is to convert the font into a format that can be understood by the µGFX decoder. This can be done very easily using our [http://ugfx.org/fontconvert.php online converter].
+
The next step is to convert the font into a format that can be understood by the µGFX decoder. This can be done very easily using our [http://fonts.ugfx.org online converter].
−
The converter does allow you to set the font size, enable or disable anti-aliasing and also filter for certain glyphs. The latter is very essential to keep the font size low. This [http://en.wikipedia.org/wiki/Basic_multilingual_plane#Basic_Multilingual_Plane table] might help to choose the correct glyph range. A click on the button «Get .c file» will offer you a C file to download after certain moments. Please click that button just once. It can take up to a minute to convert a larger font.
+
The converter allows you to set the font size, enable or disable anti-aliasing and filter for certain characters. Filtering un-needed characters is essential to keep the font size low. This [http://en.wikipedia.org/wiki/Basic_multilingual_plane#Basic_Multilingual_Plane table] might help you choose the correct character range. A click on the button «Get .c file» will offer you a C file to download after a few moments. Please click that button just once. It can take up to a minute to convert a larger font.
  
 
=== 3. Implement the font ===
 
=== 3. Implement the font ===
−
The generated C file must be added to your build chain (Add it as any other C source).
+
Place the downloaded c file inside your project directory and name it '''userfonts.h'''. Alternatively write a '''userfonts.h''' file that includes each of your downloaded font c files. In your [[gfxconf.h]], enable the following setting:
 +
<syntaxhighlight lang=c>
 +
#define GDISP_INCLUDE_USER_FONTS TRUE
 +
</syntaxhighlight>
  
 
=== 4. Open the font ===
 
=== 4. Open the font ===
Line 57: Line 141:
 
For a more detailed guide on how to add your own font, see [[Cyrillic]].
 
For a more detailed guide on how to add your own font, see [[Cyrillic]].
  
 +
== Font metrics ==
 +
The GDISP API provides several function to retrieve information about font metrics:
  
 +
<source lang=c>
 +
typedef enum fontmetric {
 +
    fontHeight,
 +
    fontDescendersHeight,
 +
    fontLineSpacing,
 +
    fontCharPadding,
 +
    fontMinWidth,
 +
    fontMaxWidth,
 +
    fontBaselineX,
 +
    fontBaselineY
 +
} fontmetric_t;
  
 +
gCoord gdispGetFontMetric(gFont font, fontmetric_t metric);
 +
gCoord gdispGetCharWidth(char c, gFont font);
 +
gCoord gdispGetStringWidth(const char* str, gFont font);
 +
gCoord gdispGetStringWidthCount(const char* str, gFont font, uint16_t count);
 +
</source>
 
[[Category:GDISP]]
 
[[Category:GDISP]]
 +
 +
== Disclaimer ==
 +
µGFX comes with a built-in support of [https://code.google.com/p/mcufont/ mcufont]. The author of the mcufont project provides a re-licensed version of his works to the µGFX projects.

Latest revision as of 13:47, 30 July 2021

Features

The µGFX font rendering engine provides the following features:

Word-Wrapping

The word wrapping feature can be enabled by setting GDISP_NEED_TEXT_WORDWRAP to TRUE.

Word wrapping only has an effect when using gdispDrawStringBox() or gdispFillStringBox(). When the word wrapping feature is not enabled the string will simply be cut-off at the border of the specified box.

Unicode

Unicode support can be enabled by setting GDISP_NEED_TEXT_UTF8 to TRUE.

Unicode support allows to display fonts of many different languages such as English, French, German, Russian (Cyrillic), Chinese, Japanese and so on. For information about cyrillic font support, see Cyrillic.

Anti-Aliasing

To use the anti-aliasing font feature, the following three conditions have to be fulfilled:

  1. Using an anti-aliased font
  2. GDISP_NEED_ANTIALIAS needs to be set to TRUE
  3. Either have GDISP_NEED_PIXELREAD set to TRUE or using one of the text drawing functions that have a background color parameter.

Note that you can use normal (non anti-aliased) fonts along with anti-aliased ones without any problems.

Kerning

Kerning support can be enabled by setting GDISP_NEED_TEXT_KERNING to TRUE.

TrueType-Font support

Any TrueType-Font available in a *.ttf or a *.bdf file format can be used in uGFX. See Adding Fonts.

Fonts

Every font that's available in a .ttf or .bdf format can be displayed through µGFX. However, we already added a bunch of fonts in different sizes and versions which should cover most use cases. Use the Font name as the parameter of the gdispOpenFont() routine.

Font Font name
DejaVu Sans 10 DejaVuSans10
DejaVu Sans 12 DejaVuSans12
DejaVu Sans 12 Bold DejaVuSansBold12
DejaVu Sans 12 Anti-Aliased DejaVuSans12_aa
DejaVu Sans 12 Anti-Aliased Bold DejaVuSansBold12_aa
DejaVu Sans 16 DejaVuSans16
DejaVu Sans 16 Anti-Aliased DejaVuSans16_aa
DejaVu Sans 20 DejaVuSans20
DejaVu Sans 20 Anti-Aliased DejaVuSans20_aa
DejaVu Sans 24 DejaVuSans24
DejaVu Sans 24 Anti-Aliased DejaVuSans24_aa
DejaVu Sans 32 DejaVuSans32
DejaVu Sans 32 Anti-Aliased DejaVuSans32_aa
Fixed 10x20 fixed_10x20
Fixed 7x14 fixed_7x14
Fixed 5x8 fixed_5x8
UI1 UI1
UI1 Double UI1 Double
UI1 Narrow UI1 Narrow
UI2 UI2
UI2 Double UI2 Double
UI2 Narrow UI2 Narrow
Large numbers LargeNumbers

Note that each of these fonts has to be enabled in your configuration file.

The UI fonts are created by the µGFX developers to provide a default font. The UI fonts stand under the GFX license and should therefore be used in preference to other fonts if suitable. The other fonts are under their own respective licenses.

Usage

Before you can use a font, you first have to open it by calling gdispOpenFont(). 

gFont font = gdispOpenFont("DejaVuSans32_aa");

Note: When the font name specified could not be found, the last enabled font in the configuration file will be used.

You should call gdispCloseFont() to release any allocated resources if you don't need a font any longer: 

gdispCloseFont(font);

After opening a font, the font variable can now be passed to any API call that takes a font parameter. You may start by reading through the basic GDISP text drawing routines before you take a look at the different GWIN system.

Adding fonts

The following step-by-step guide will lead you through the process of adding a custom *.ttf font. This guide works for every font, not only ASCII but also cyrillic and any other unicode compatible ones.

1. Acquire a font

First of all, you'll need a font in the *.ttf source. You can find plenty of these using google. Please notice their licenses.

2. Convert the font

The next step is to convert the font into a format that can be understood by the µGFX decoder. This can be done very easily using our online converter. The converter allows you to set the font size, enable or disable anti-aliasing and filter for certain characters. Filtering un-needed characters is essential to keep the font size low. This table might help you choose the correct character range. A click on the button «Get .c file» will offer you a C file to download after a few moments. Please click that button just once. It can take up to a minute to convert a larger font.

3. Implement the font

Place the downloaded c file inside your project directory and name it userfonts.h. Alternatively write a userfonts.h file that includes each of your downloaded font c files. In your gfxconf.h, enable the following setting: 

#define GDISP_INCLUDE_USER_FONTS	TRUE

4. Open the font

You can now open and use this font as any other one. If you're curious about the parameter of gdispOpenFont(), you can either use the full_name or the short_name field that can be found in the struct at the very bottom of the C file (first and second entry). Please note that you need to configure your text editor to operate in UTF-8 mode, when you want to display those fonts successfully.

For a more detailed guide on how to add your own font, see Cyrillic.

Font metrics

The GDISP API provides several function to retrieve information about font metrics: 

typedef enum fontmetric {
    fontHeight,
    fontDescendersHeight,
    fontLineSpacing,
    fontCharPadding,
    fontMinWidth,
    fontMaxWidth,
    fontBaselineX,
    fontBaselineY
} fontmetric_t;
 
gCoord gdispGetFontMetric(gFont font, fontmetric_t metric);
gCoord gdispGetCharWidth(char c, gFont font);
gCoord gdispGetStringWidth(const char* str, gFont font);
gCoord gdispGetStringWidthCount(const char* str, gFont font, uint16_t count);

Disclaimer

µGFX comes with a built-in support of mcufont. The author of the mcufont project provides a re-licensed version of his works to the µGFX projects.

Retrieved from "https://wiki.ugfx.io/index.php?title=Font_rendering&oldid=1912"