.. _built_in_fonts:

==============
Built-In Fonts
==============

Overview
********

There are several built-in fonts in different sizes, which can be
enabled in ``lv_conf.h`` with *LV_FONT_...* defines.


The built-in fonts are **global variables** with names like
:cpp:var:`lv_font_montserrat_16` for a 16 px height font. To use them in a
style, just add a pointer to a font variable like this:

.. code-block:: c

    lv_style_set_text_font(&my_style, &lv_font_montserrat_28);


The built-in fonts with ``bpp = 4`` contain the ASCII characters and use
the `Montserrat <https://fonts.google.com/specimen/Montserrat>`__ font.

In addition to the ASCII range all the :ref:`predefined symbols <font_symbols>` are
added to the built-in fonts from the
`FontAwesome <https://fontawesome.com/>`__ font.


Normal Fonts
************

The following fonts contain all ASCII characters, the degree symbol (U+00B0), the
bullet symbol (U+2022) and the built-in symbols (see below).

- :c:macro:`LV_FONT_MONTSERRAT_12`: 12 px font
- :c:macro:`LV_FONT_MONTSERRAT_14`: 14 px font
- :c:macro:`LV_FONT_MONTSERRAT_16`: 16 px font
- :c:macro:`LV_FONT_MONTSERRAT_18`: 18 px font
- :c:macro:`LV_FONT_MONTSERRAT_20`: 20 px font
- :c:macro:`LV_FONT_MONTSERRAT_22`: 22 px font
- :c:macro:`LV_FONT_MONTSERRAT_24`: 24 px font
- :c:macro:`LV_FONT_MONTSERRAT_26`: 26 px font
- :c:macro:`LV_FONT_MONTSERRAT_28`: 28 px font
- :c:macro:`LV_FONT_MONTSERRAT_30`: 30 px font
- :c:macro:`LV_FONT_MONTSERRAT_32`: 32 px font
- :c:macro:`LV_FONT_MONTSERRAT_34`: 34 px font
- :c:macro:`LV_FONT_MONTSERRAT_36`: 36 px font
- :c:macro:`LV_FONT_MONTSERRAT_38`: 38 px font
- :c:macro:`LV_FONT_MONTSERRAT_40`: 40 px font
- :c:macro:`LV_FONT_MONTSERRAT_42`: 42 px font
- :c:macro:`LV_FONT_MONTSERRAT_44`: 44 px font
- :c:macro:`LV_FONT_MONTSERRAT_46`: 46 px font
- :c:macro:`LV_FONT_MONTSERRAT_48`: 48 px font

Special Fonts
*************

-  :c:macro:`LV_FONT_MONTSERRAT_28_COMPRESSED`: Same as normal 28 px font but stored as a :ref:`fonts_compressed` with 3 bpp
-  :c:macro:`LV_FONT_DEJAVU_16_PERSIAN_HEBREW`: 16 px font with normal range + Hebrew, Arabic, Persian letters and all their forms
-  :c:macro:`LV_FONT_SOURCE_HAN_SANS_SC_16_CJK`: 16 px font with normal range plus 1000 of the most common CJK radicals
-  :c:macro:`LV_FONT_UNSCII_8`: 8 px pixel perfect font with only ASCII characters
-  :c:macro:`LV_FONT_UNSCII_16`: 16 px pixel perfect font with only ASCII characters


.. _add_new_builtin_font:

Adding a New Font
*****************

There are several ways to add a new font to your project:

1. The simplest method is to use the `Online font converter <https://lvgl.io/tools/fontconverter>`__.
   Just set the parameters, click the *Convert* button, copy the font to your project
   and use it. **Be sure to carefully read the steps provided on that site
   or you will get an error while converting.**
2. Use the `Offline font converter <https://github.com/lvgl/lv_font_conv>`__.
   (Requires Node.js to be installed)
3. If you want to create something like the built-in
   fonts (Montserrat font and symbols) but in a different size and/or
   ranges, you can use the ``built_in_font_gen.py`` script in
   ``lvgl/scripts/built_in_font`` folder. (This requires Python and
   https://github.com/lvgl/lv_font_conv/ to be installed.)

To declare a font in a file, use :cpp:expr:`LV_FONT_DECLARE(my_font_name)`.

To make fonts globally available (like the built-in fonts), add them to
:c:macro:`LV_FONT_CUSTOM_DECLARE` in ``lv_conf.h``.


.. _fonts_compressed:

Compressed Fonts
****************

The built-in font engine supports compressed bitmaps.
Compressed fonts can be generated by

- ticking the ``Compressed`` check box in the online converter
- not passing the ``--no-compress`` flag to the offline converter (compression is applied by default)

Compression is more effective with larger fonts and higher bpp. However,
it's about 30% slower to render compressed fonts. Therefore, it is
recommended to compress only the largest fonts of a user interface,
because

- they need the most memory
- they can be compressed better
- and on the likelihood that they are used less frequently than the medium-sized
  fonts, the performance cost will be smaller.

Compressed fonts also support ``bpp=3``.

