lv_font.h

API reference for lv_font.h

Summary

Functions

font/lv_font.h:251function

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)

Name	Type	Description
`font`	`lv_font_t *`	pointer to a font
`kerning`	`lv_font_kerning_t`	`LV_FONT_KERNING_NORMAL` (default) or `LV_FONT_KERNING_NONE`

Enums

font/lv_font.h:36enum

lv_font_glyph_format_t

The font format.

Name	Value	Description
`LV_FONT_GLYPH_FORMAT_NONE`	`0`	Maybe not visible Legacy simple formats
`LV_FONT_GLYPH_FORMAT_A1`	`0x01`	1 bit per pixel
`LV_FONT_GLYPH_FORMAT_A2`	`0x02`	2 bit per pixel
`LV_FONT_GLYPH_FORMAT_A3`	`0x03`	3 bit per pixel
`LV_FONT_GLYPH_FORMAT_A4`	`0x04`	4 bit per pixel
`LV_FONT_GLYPH_FORMAT_A8`	`0x08`	8 bit per pixel
`LV_FONT_GLYPH_FORMAT_IMAGE`	`0x19`	Image format Advanced formats
`LV_FONT_GLYPH_FORMAT_VECTOR`	`0x1A`	Vectorial format
`LV_FONT_GLYPH_FORMAT_SVG`	`0x1B`	SVG format
`LV_FONT_GLYPH_FORMAT_CUSTOM`	`0xFF`	Custom format

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`

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_manager_create_font — param kerning
lv_font_set_kerning — param kerning
lv_tiny_ttf_create_data_ex — param kerning

Structs

struct

lv_font_glyph_dsc_t

Describes the properties of a glyph.

Member	Type	Description
`resolved_font`	`const lv_font_t *`	Pointer to a font where the glyph was actually found after handling fallbacks
`entry`	`lv_cache_entry_t *`	The cache entry of the glyph draw data. Used by the font cache
`index`	`uint32_t`	Glyph descriptor index
`src`	`const void *`	Pointer to the source data used by image fonts
`gid`	`union lv_font_glyph_dsc_t`	The index of the glyph in the font file. Used by the font cache
`format`	`lv_font_glyph_format_t`	Font format of the glyph see lv_font_glyph_format_t
`outline_stroke_width`	`int32_t`	used with freetype vector fonts - width of the letter border
`adv_w`	`uint16_t`	The glyph needs this space. Draw the next glyph after this width.
`box_w`	`uint16_t`	Width of the glyph's bounding box
`box_h`	`uint16_t`	Height of the glyph's bounding box
`ofs_x`	`int16_t`	x offset of the bounding box
`ofs_y`	`int16_t`	y offset of the bounding box
`stride`	`uint16_t`	Bytes in each line. If 0 than there is no padding at the end of the line.
`is_placeholder`	`uint8_t`	Glyph is missing. But placeholder will still be displayed
`req_raw_bitmap`	`uint8_t`	0: 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 9 functions

lv_vg_lite_bitmap_font_cache_get — param g_dsc
lv_font_get_bitmap_fmt_txt — param g_dsc
lv_font_get_glyph_dsc_fmt_txt — param dsc_out
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_glyph_dsc_compare — param lhs
lv_font_glyph_dsc_compare — param rhs

struct

_lv_font_t

Describe the properties of a font

Member	Type	Description
`dsc`	`const void *`	Store implementation specific or run_time data or caching here
`fallback`	`const lv_font_t *`	Fallback font for missing glyph. Resolved recursively
`user_data`	`void *`	Custom user data for font.
`get_glyph_dsc`	`bool()(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_bitmap`	`const 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_glyph`	`void()(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_height`	`int32_t`	The real line height where any text fits
`base_line`	`int32_t`	Base line measured from the bottom of the line_height
`cap_height`	`int32_t`	Cap height of the font
`x_height`	`int32_t`	x-height of the font
`subpx`	`uint8_t`	An element of `lv_font_subpx_t`
`kerning`	`uint8_t`	An element of `lv_font_kerning_t`
`static_bitmap`	`uint8_t`	The font will be used as static bitmap
`underline_position`	`int8_t`	Distance between the top of the underline and base line (< 0 means below the base line)
`underline_thickness`	`int8_t`	Thickness of the underline

struct

_lv_font_class_t

Member	Type	Description
`create_cb`	`lv_font_t ()(const lv_font_info_t info, const void src)`	Font creation callback function
`delete_cb`	`void()(lv_font_t font)`	Font deletion callback function
`dup_src_cb`	`void ()(const void *src)`	Font source duplication callback function
`free_src_cb`	`void()(void src)`	Font source free callback function

struct

_lv_font_info_t

Member	Type	Description
`name`	`const char *`	Font name, used to distinguish different font resources
`class_p`	`const lv_font_class_t *`	Font backend implementation
`size`	`uint32_t`	Font size in pixel
`render_mode`	`uint32_t`	Font rendering mode, see `lv_freetype_font_render_mode_t`
`style`	`uint32_t`	Font style, see `lv_freetype_font_style_t`
`kerning`	`lv_font_kerning_t`	Font kerning, see `lv_font_kerning_t`

Macros

font/lv_font.h:278macro

LV_FONT_DECLARE

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

Variables

font/lv_font.h:293variable

lv_font_montserrat_14

const lv_font_t lv_font_montserrat_14

lv_font.h

Functions

lv_font_set_kerning

Enums

lv_font_glyph_format_t

lv_font_subpx_t

lv_font_kerning_t

Structs

lv_font_glyph_dsc_t

_lv_font_t

_lv_font_class_t

_lv_font_info_t

Macros

LV_FONT_DECLARE

Variables

lv_font_montserrat_14

Dependencies

On this page