APIPublic APIFont

lv_font.h

API reference for lv_font.h

Report on GitHub
See Also: Private HeaderThis header has a companion private implementation with internal data structures.lv_font_private.h
Summary
10Functions
3Enums
4Structs
1Macros
1Variables

Functions

public/font/lv_font.h:253function

lv_font_set_kerning

Configure the use of kerning information stored in a font

 
void lv_font_set_kerning(lv_font_t *font, lv_font_kerning_t kerning)
Parameters
NameTypeDescription
fontlv_font_t *pointer to a font
kerninglv_font_kerning_tLV_FONT_KERNING_NORMAL (default) or LV_FONT_KERNING_NONE

Enums

public/font/lv_font.h:35enum

lv_font_glyph_format_t

The font format.

NameValueDescription
LV_FONT_GLYPH_FORMAT_NONE0Maybe not visible Legacy simple formats
LV_FONT_GLYPH_FORMAT_A10x011 bit per pixel
LV_FONT_GLYPH_FORMAT_A20x022 bit per pixel
LV_FONT_GLYPH_FORMAT_A30x033 bit per pixel
LV_FONT_GLYPH_FORMAT_A40x044 bit per pixel
LV_FONT_GLYPH_FORMAT_A80x088 bit per pixel
LV_FONT_GLYPH_FORMAT_IMAGE0x19Image format Advanced formats
LV_FONT_GLYPH_FORMAT_VECTOR0x1AVectorial format
LV_FONT_GLYPH_FORMAT_SVG0x1BSVG format
LV_FONT_GLYPH_FORMAT_CUSTOM0xFFCustom format
public/font/lv_font.h:78enum

lv_font_subpx_t

The bitmaps might be upscaled by 3 to achieve subpixel rendering.

Name
LV_FONT_SUBPX_NONE
LV_FONT_SUBPX_HOR
LV_FONT_SUBPX_VER
LV_FONT_SUBPX_BOTH
public/font/lv_font.h:86enum

lv_font_kerning_t

Adjust letter spacing for specific character pairs.

Name
LV_FONT_KERNING_NORMAL
LV_FONT_KERNING_NONE
Used by 3 functions
  • lv_font_set_kerning — param kerning
  • lv_font_manager_create_font — param kerning
  • lv_tiny_ttf_create_data_ex — param kerning

Structs

struct

lv_font_glyph_dsc_t

Describes the properties of a glyph.

MemberTypeDescription
resolved_fontconst lv_font_t *Pointer to a font where the glyph was actually found after handling fallbacks
entryvoid *The cache entry of the glyph draw data. Used by the font cache
indexuint32_tGlyph descriptor index
srcconst void *Pointer to the source data used by image fonts
gidunion lv_font_glyph_dsc_tThe index of the glyph in the font file. Used by the font cache
formatlv_font_glyph_format_tFont format of the glyph see lv_font_glyph_format_t
outline_stroke_widthint32_tused with freetype vector fonts - width of the letter border
adv_wuint16_tThe glyph needs this space. Draw the next glyph after this width.
box_wuint16_tWidth of the glyph's bounding box
box_huint16_tHeight of the glyph's bounding box
ofs_xint16_tx offset of the bounding box
ofs_yint16_ty offset of the bounding box
strideuint16_tBytes in each line. If 0 than there is no padding at the end of the line.
is_placeholderuint8_tGlyph is missing. But placeholder will still be displayed
req_raw_bitmapuint8_t0: Get bitmap should return an A8 or ARGB8888 image. 1: return the bitmap as it is (Maybe A1/2/4 or any proprietary formats).
Used by 13 functions
  • lv_font_get_glyph_bitmap — param g_dsc
  • lv_font_get_glyph_static_bitmap — param g_dsc
  • lv_font_get_glyph_dsc — param dsc_out
  • lv_font_glyph_release_draw_data — param g_dsc
  • lv_font_get_bitmap_fmt_txt — param g_dsc
  • lv_font_get_glyph_dsc_fmt_txt — param dsc_out
  • lv_vg_lite_bitmap_font_cache_get — param g_dsc
  • lv_font_glyph_dsc_compare — param lhs
  • lv_font_glyph_dsc_compare — param rhs
  • lv_font_get_glyph_bitmap_internal — param g_dsc
  • lv_font_get_glyph_static_bitmap_internal — param g_dsc
  • lv_font_glyph_release_draw_data_internal — param g_dsc
  • lv_font_get_glyph_dsc_internal — param dsc_out
struct

_lv_font_t

Describe the properties of a font

MemberTypeDescription
dscconst void *Store implementation specific or run_time data or caching here
fallbackconst lv_font_t *Fallback font for missing glyph. Resolved recursively
user_datavoid *Custom user data for font.
get_glyph_dscbool(*)(const lv_font_t *font, lv_font_glyph_dsc_t *dsc_out, uint32_t letter, uint32_t letter_next)Get a glyph's descriptor from a font.

Fills dsc_out with metrics for the glyph corresponding to letter in font. letter_next is provided for kerning. The implementation may adjust dsc_out->adv_w based on the following character. Pass 0 if there is no next character.
get_glyph_bitmapconst void *(*)(lv_font_glyph_dsc_t *g_dsc, lv_draw_buf_t *draw_buf)Get glyph draw data from a font.

Returns an opaque pointer to draw data for the glyph described by g_dsc. The concrete type and interpretation of the returned pointer depend on g_dsc->format (and related flags, e.g. whether a raw bitmap was requested).

For legacy bitmap formats (e.g. A1/A2/A3/A4/A8), the implementation may either:
- decode/decompress into the caller-provided draw_buf and return a pointer to that draw buffer (typically an lv_draw_buf_t *), or
- return a pointer to font-internal bitmap storage.

For non-bitmap formats (e.g. LV_FONT_GLYPH_FORMAT_IMAGE, vector/outline/SVG, or custom formats), the implementation typically ignores draw_buf and returns a format-specific object (such as an image source or lv_vector_path_t *).

The caller must always treat the return value as the authoritative glyph draw data and interpret it according to g_dsc->format. Do not assume the data was written into draw_buf or that it is always an alpha bitmap. The returned pointer is only valid until release_glyph is called.
release_glyphvoid(*)(const lv_font_t *font, lv_font_glyph_dsc_t *g_dsc)Release a glyph and any resources acquired during get_glyph_dsc or get_glyph_bitmap.

Must be called after the glyph bitmap is no longer needed. Releases any internal cache entry stored in g_dsc->entry by the font implementation. Calling this with a g_dsc whose entry is NULL must be treated as a no-op.
line_heightint32_tThe real line height where any text fits
base_lineint32_tBase line measured from the bottom of the line_height
cap_heightint32_tCap height of the font
x_heightint32_tx-height of the font
subpxuint8_tAn element of lv_font_subpx_t
kerninguint8_tAn element of lv_font_kerning_t
static_bitmapuint8_tThe font will be used as static bitmap
underline_positionint8_tDistance between the top of the underline and base line (< 0 means below the base line)
underline_thicknessint8_tThickness of the underline
struct

_lv_font_class_t

MemberTypeDescription
create_cblv_font_t *(*)(const lv_font_info_t *info, const void *src)Font creation callback function
delete_cbvoid(*)(lv_font_t *font)Font deletion callback function
dup_src_cbvoid *(*)(const void *src)Font source duplication callback function
free_src_cbvoid(*)(void *src)Font source free callback function
struct

_lv_font_info_t

MemberTypeDescription
nameconst char *Font name, used to distinguish different font resources
class_pconst lv_font_class_t *Font backend implementation
sizeuint32_tFont size in pixel
render_modeuint32_tFont rendering mode, see lv_freetype_font_render_mode_t
styleuint32_tFont style, see lv_freetype_font_style_t
weightint32_tFont weight for variable fonts (range 1-2000, CSS-like values 100-900; 0 = default: 400 normal, 700 if bold style)
kerninglv_font_kerning_tFont kerning, see lv_font_kerning_t

Macros

public/font/lv_font.h:280macro

LV_FONT_DECLARE

 
#define LV_FONT_DECLARE(font_name) \
    LV_ATTRIBUTE_EXTERN_DATA extern const lv_font_t font_name;

Variables

public/font/lv_font.h:295variable

lv_font_montserrat_14

 
const lv_font_t lv_font_montserrat_14

Dependencies

Indirect dependencies

Last updated on

lv_font_fmt_txt.h

API reference for lv_font_fmt_txt.h

lv_font_manager.h

API reference for lv_font_manager.h

On this page

Functionslv_font_set_kerninglv_font_get_glyph_bitmaplv_font_get_glyph_static_bitmaplv_font_get_glyph_dsclv_font_get_glyph_widthlv_font_get_line_heightlv_font_get_defaultlv_font_glyph_release_draw_datalv_font_info_is_equallv_font_has_static_bitmapEnumslv_font_glyph_format_tlv_font_subpx_tlv_font_kerning_tStructslv_font_glyph_dsc_t_lv_font_t_lv_font_class_t_lv_font_info_tMacrosLV_FONT_DECLAREVariableslv_font_montserrat_14Dependencies