Labs / LVGL / 02 LVGL Basic Knowledge and Concepts

II. Visual Style and Resource System: GUI Skins and Creatives

Author: Li Zisheng · Source: FreakStudio open documentation, v1.1 · License: CC BY 4.0

Contents

Styles serve as the core for controlling the visual presentation of objects. Together with basic resources such as colors, fonts and images, they collectively define the visual style of a GUI, and support highly customized and thematized configurations.

First, memorize the 3 most fundamental concepts:

Official conceptPlain-language understandingExample
StyleThe widget's "appearance set"Can define an appearance such as "red background, 2px black border, white text", like dressing up a widget
StateThe widget's "behavior state"A button displayed normally (default), pressed by a finger, selected, or disabled, like a person standing / sitting / running
PartA complex widget's "components"A slider is split into: background (base), progress bar (indicator), and knob (adjustment handle); each part can be styled separately

At the same time, there are two key rules as follows:

Basic visual resources include:

2.1 Style System (Styles)

Styles in LVGL serve as the core mechanism for controlling the appearance of UI components (objects), which are designed with reference to CSS while adapted to the lightweight characteristics of embedded GUIs.

First, quickly align the core terms of LVGL styling through CSS analogy:

LVGL conceptCSS equivalent conceptPlain explanation
lv_style_tCSS class (.btn)Container that stores style properties (such as border, color, font)
Target PartCSS pseudo-element (::after)A component's parts (such as a slider's knob, a button's text area)
Target StateCSS pseudo-class (:hover)A component's state (such as pressed, focused, disabled, default)
Style cascadingCSS class stacking (.btn.red)Multiple styles are stacked, with properties overridden as needed
Style priorityCSS priority rulesLater-added styles > earlier-added ones; local styles > normal styles
InheritanceCSS inheritance (such as text color)Child components can inherit some style properties from the parent component

2.2 State

The State in LVGL refers to binary flag bits that describe the current behavior/status of an object (such as a button or slider), whose core function is to bind different styles to objects in different states or state combinations, so as to realize interactive effects such as "changing color on click, adding a border when focused". In mpy, state constants are called in the form of lv.STATE.XXX, and the corresponding relationship is as follows:

MicroPython state constantValueMeaningPriority (higher value = higher priority)
lv.STATE.DEFAULT0x0000Normal / released state (default fallback)Lowest
lv.STATE.CHECKED0x0001Checked / toggled state (e.g. a checkbox is checked)↑
lv.STATE.FOCUSED0x0002Focused state (triggered by keyboard / touch / mouse)↑
lv.STATE.FOCUS_KEY0x0004Focus triggered only by keyboard / encoder (not touch)↑
lv.STATE.EDITED0x0008Encoder edit state↑
lv.STATE.HOVERED0x0010Mouse hover (not supported yet)↑
lv.STATE.PRESSED0x0020Pressed state↑
lv.STATE.SCROLLED0x0040Scrolled state↑
lv.STATE.DISABLED0x0080Disabled state↑
lv.STATE.USER_1 ~ 40x1000+Custom state (extend as needed)Highest (user-defined)
0x0000 0x0001

When LVGL matches styles to objects, it follows the logic of " states with higher priority override those with lower priority, and fall back to the default if no match is found ", with the core rules as follows:

Suppose the following styles are set for the button:

Style matching results in different states:

2.3 Cascading Styles

You don't need to define all appearance attributes in a single style; you can apply multiple styles to the same object. Styles added later have higher priority (and will override the same attributes of previously added styles), however, state priority always takes precedence over cascade priority.

2.4 Style Inheritance

Some attributes (mainly text-related attributes such as font, text color, and text alignment) can be inherited from the parent object, and the parent object's style will be looked up upward only when none of the child object's own styles (including the default state) have set this attribute.

The parent object uses its current state to provide inherited values. For example, when a button is in the "pressed" state, if the text label inside the button has no text color configured, it will inherit the text color of the button's "pressed" state instead of the default state.

2.5 Parts

LVGL widgets consist of multiple "functional components", each of which can be styled independently (similar to CSS pseudo-elements such as:: after), enabling differentiated appearances for different areas of the widget.

Predefined Core Components (General):

Predefined Core Component Names

Meaning

LV_PART_MAIN

Control body (e. g., the background of a button, the overall background of a slider)

LV_PART_INDICATOR

Indicators (such as the Progress Bar of a slider, the on indicator of a switch, and the check box of a checkbox)

LV_PART_KNOB

Adjustment handle / (e. g. the draggable button of a slider, the adjustment point of a scroll wheel)

LV_PART_SCROLLBAR

scroll bar

LV_PART_SELECTED

Selected item (e. g. the selected entry in a drop-down box)

LV_PART_CURSOR

Cursor (e. g., the input cursor in a text box)

Example: The slider consists of three components: MAIN (background), INDICATOR (Progress Bar), and (adjustment ), and you may set the to red, the Progress Bar to blue, and the background to gray respectively.

2.6 Style Initialization and Attribute Manipulation

Essentially, a style is a variable of type lv_style_t, and all operations on it must follow fixed rules:

II. Visual Style and Resource System: GUI Skins and Creatives

2.7 Add / Replace / Remove Styles for Controls

A style takes effect only when bound to a control, and the core operation revolves around the "selector"(a combination of a component and its state):

2.8 Style Change Notification

After modifying the style that has been bound to a control, you need to actively notify the control to refresh it, otherwise the style will not take effect:

II. Visual Style and Resource System: GUI Skins and Creatives
II. Visual Style and Resource System: GUI Skins and Creatives
II. Visual Style and Resource System: GUI Skins and Creatives

2.9 Obtain the Final Style Property Value of the Control

You can obtain the final property value of a certain component of a control via get_style_<property_name>(control, component), and this function will automatically synthesize the following:

2.10 Local Styles

Analogous to inline styles in CSS (<div style="color:red">), but with more powerful features:

2.11 Transitions

When switching the default state, style properties change immediately; transitions enable animated gradients (e. g., a 300ms gradient of the background color when a button is pressed):

2.12 Opacity, Blend Mode and Transform

When setting opa (opacity), transform_angle (rotation), transform_zoom (scaling) and other properties:

2.13 Themes

A theme is a collection of styles used to unify the default appearance of the entire interface:

2.14 Summary Table of Style Attributes

2.14.1 Dimensions and Location (Size and position)

Property nameFunction descriptionDefault valueInheritedAffects layoutExtra draw
widthSets the object width; supports pixels / percentage / LV_SIZE_CONTENTWidget-specificNoYesNo
min_widthMinimum width limit0NoYesNo
max_widthMaximum width limitLV_COORD_MAXNoYesNo
heightSets the object height; supports pixels / percentage / LV_SIZE_CONTENTWidget-specificNoYesNo
min_heightMinimum height limit0NoYesNo
max_heightMaximum height limitLV_COORD_MAXNoYesNo
xX coordinate relative to the alignment reference0NoYesNo
yY coordinate relative to the alignment reference0NoYesNo
alignAlignment relative to the parentLV_ALIGN_DEFAULTNoYesNo
transform_widthWiden the object in both directions0NoNoYes
transform_heightHeighten the object in both directions0NoNoYes
translate_xX offset after layout0NoYesNo
translate_yY offset after layout0NoYesNo
transform_zoomZoom; 256 = original size0NoYesYes
transform_angleRotation angle (in units of 0.1°)0NoYesYes
transform_pivot_xTransform pivot X coordinate0NoNoNo
transform_pivot_yTransform pivot Y coordinate0NoNoNo

2.14.2 Padding

Property nameFunction descriptionDefault valueInheritedAffects layoutExtra draw
pad_topTop padding0NoYesNo
pad_bottomBottom padding0NoYesNo
pad_leftLeft padding0NoYesNo
pad_rightRight padding0NoYesNo
pad_rowLayout row spacing0NoYesNo
pad_columnLayout column spacing0NoYesNo

2.14.3 Margin

Property nameFunction descriptionDefault valueInheritedAffects layoutExtra draw
margin_topTop margin0NoYesNo
margin_bottomBottom margin0NoYesNo
margin_leftLeft margin0NoYesNo
margin_rightRight margin0NoYesNo

2.14.4 Background

Property nameFunction descriptionDefault valueInheritedAffects layoutExtra draw
bg_colorBackground color0xffffffNoNoNo
bg_opaBackground opacityLV_OPA_TRANSPNoNoNo
bg_grad_colorBackground gradient color0x000000NoNoNo
bg_grad_dirGradient directionLV_GRAD_DIR_NONENoNoNo
bg_main_stopMain color gradient start point0NoNoNo
bg_grad_stopGradient color start point255NoNoNo
bg_gradGradient descriptorNULLNoNoNo
bg_dither_modeGradient dither modeLV_DITHER_NONENoNoNo
bg_img_srcBackground image sourceNULLNoNoYes
bg_img_opaBackground image opacityLV_OPA_COVERNoNoNo
bg_img_recolorBackground image recolor color0x000000NoNoNo
bg_img_recolor_opaImage recolor intensityLV_OPA_TRANSPNoNoNo
bg_img_tiledBackground image tiling0NoNoNo

2.14.5 Border

Property nameFunction descriptionDefault valueInheritedAffects layoutExtra draw
border_colorBorder color0x000000NoNoNo
border_opaBorder opacityLV_OPA_COVERNoNoNo
border_widthBorder width (pixels only)0NoYesNo
border_sideBorder sides to displayLV_BORDER_SIDE_NONENoNoNo
border_postBorder drawing timing (after / before children)0NoNoNo

2.14.6 Outline

Property nameFunction descriptionDefault valueInheritedAffects layoutExtra draw
outline_widthOutline width0NoNoYes
outline_colorOutline color0x000000NoNoNo
outline_opaOutline opacityLV_OPA_COVERNoNoYes
outline_padOutline-to-object spacing0NoNoYes

2.14.7 Shadow

Property nameFunction descriptionDefault valueInheritedAffects layoutExtra draw
shadow_widthShadow width0NoNoYes
shadow_offset_xShadow X offset0NoNoYes
shadow_offset_yShadow Y offset0NoNoYes
shadow_spreadShadow spread0NoNoYes
shadow_colorShadow color0x000000NoNoNo
shadow_opaShadow opacityLV_OPA_COVERNoNoYes

2.14.8 Image

Property nameFunction descriptionDefault valueInheritedAffects layoutExtra draw
img_opaImage opacityLV_OPA_COVERNoNoNo
img_recolorImage recolor blend color0x000000NoNoNo
img_recolor_opaImage recolor intensity0NoNoNo

2.14.9 Line

Property nameFunction descriptionDefault valueInheritedAffects layoutExtra draw
line_widthLine width0NoNoYes
line_dash_widthDash width0NoNoYes
line_dash_gapDash gap0NoNoYes
line_roundedLine end rounding0NoNoYes
line_colorLine color0x000000NoNoNo
line_opaLine opacityLV_OPA_COVERNoNoNo

2.14.10 Arc

Property nameFunction descriptionDefault valueInheritedAffects layoutExtra draw
arc_widthArc thickness0NoNoYes
arc_roundedArc end rounding0NoNoYes
arc_colorArc color0x000000NoNoNo
arc_opaArc opacityLV_OPA_COVERNoNoNo
arc_img_srcArc mask imageNULLNoNoNo

2.14.11 Text

Property nameFunction descriptionDefault valueInheritedAffects layoutExtra draw
text_colorText color (hexadecimal RGB value)0x000000 (black)YesNoNo
text_opaText opacity, value range:
- 0/LV_OPA_TRANSP (fully transparent)
- 255/LV_OPA_COVER (fully opaque)
- 10~90/LV_OPA_10~LV_OPA_90 (semi-transparent)
LV_OPA_COVERYesNoNo
text_fontText font (pointer to type lv_font_t)LV_FONT_DEFAULT (default font)YesYesNo
text_letter_spaceLetter spacing (unit: pixels)0YesYesNo
text_line_spaceLine spacing for multi-line text (unit: pixels)0YesYesNo
text_decorText decoration, supports bitwise OR combination:
- LV_TEXT_DECOR_NONE (no decoration)
- LV_TEXT_DECOR_UNDERLINE (underline)
- LV_TEXT_DECOR_STRIKETHROUGH (strikethrough)
LV_TEXT_DECOR_NONEYesNoNo
text_alignText alignment within a line (affects only text lines, not the object itself):
- LV_TEXT_ALIGN_LEFT (left aligned)
- LV_TEXT_ALIGN_CENTER (center aligned)
- LV_TEXT_ALIGN_RIGHT (right aligned)
- LV_TEXT_ALIGN_AUTO (auto, adapts to the text base direction)
LV_TEXT_ALIGN_AUTOYesYesNo

2.14.12 Miscellaneous

Property nameFunction descriptionDefault valueInheritedAffects layoutExtra draw
radiusCorner radius0NoNoNo
clip_cornerClip overflow content at rounded corners0NoNoNo
opaOverall object opacity scalingLV_OPA_COVERYesNoNo
color_filter_dscColor filter descriptorNULLNoNoNo
color_filter_opaColor filter intensityLV_OPA_TRANSPNoNoNo
animAnimation templateNULLNoNoNo
anim_timeAnimation duration (ms)0NoNoNo
anim_speedAnimation speed (px/sec)0NoNoNo
transitionStyle transition descriptorNULLNoNoNo
blend_modeColor blend modeLV_BLEND_MODE_NORMALNoNoNo
layoutChild widget layout0NoYesNo
base_dirText base direction (LTR/RTL)LV_BASE_DIR_AUTOYesYesNo

2.15 Colors

2.15.1 Core Basic Knowledge

The color module of LVGL is the underlying core of UI rendering, which is responsible for color creation, format conversion, color adjustment and transparency control. The core principles of its design are as follows: Unified color interface —— No matter what the system-configured color depth (LV_COLOR_DEPTH) is, all APIs interact based on the lv_color_t type (fixed RGB888 format), and the framework automatically handles the underlying color depth conversion without requiring developers to pay extra attention.

lv_color_t is the standard type for color storage in LVGL, with the following core features:

RGB is the most commonly used color definition method for embedded UIs, and LVGL provides three convenient interfaces:

Interface formPurposeExample
lv_color_make(r,g,b)Create color dynamically (runtime)lv_color_t c = lv_color_make(255,0,0); (pure red)
LV_COLOR_MAKE(r,g,b)Constant initialization (compile time)const lv_color_t c = LV_COLOR_MAKE(0,255,0); (pure green)
lv_color_hex(0xRRGGBB)6-digit hexadecimal (RR = red, GG = green, BB = blue)lv_color_t c = lv_color_hex(0x0000FF); (pure blue)
lv_color_hex3(0xRGB)3-digit shorthand hexadecimal (automatically expanded to 6 digits)lv_color_t c = lv_color_hex3(0x123); (equivalent to 0x112233)
to_u16 to_u32 RGB888

2.15.2 Methods for Creating Colors

2.15.1.1 RGB Mode Creation (the most basic method, directly specifying red/green/blue)

RGB is the most commonly used color definition method for embedded UIs, and LVGL provides three convenient interfaces:

Interface formPurposeExample
lv_color_make(r,g,b)Create color dynamically (runtime)lv_color_t c = lv_color_make(255,0,0); (pure red)
LV_COLOR_MAKE(r,g,b)Constant initialization (compile time)const lv_color_t c = LV_COLOR_MAKE(0,255,0); (pure green)
lv_color_hex(0xRRGGBB)6-digit hexadecimal (RR = red, GG = green, BB = blue)lv_color_t c = lv_color_hex(0x0000FF); (pure blue)
lv_color_hex3(0xRGB)3-digit shorthand hexadecimal (automatically expanded to 6 digits)lv_color_t c = lv_color_hex3(0x123); (equivalent to 0x112233)
2.15.1.2 HSV Mode Creation (Suitable for Dynamic Color Adjustment/Gradient)

HSV (Hue, Saturation, Value) better aligns with the human eye's perception of color, making it suitable for scenarios that require color gradients and dynamic hue adjustment:

Core conversion function:

2.15.1.3 Palette Creation (Material Design Preset Colors, Simplified UI Color Matching)

LVGL has a built-in Material Design color palette that provides 19 base colors, each consisting of a main color, 4 dark variants and 5 light variants, eliminating the need for manual RGB value adjustment and ensuring consistent UI colors.

How to use the palette:

2.15.3 Modification and Blending of Colors

LVGL provides convenient functions to adjust color brightness and blend two colors, meeting the needs of dynamic UIs (such as button pressed/hover states, gradient backgrounds):

Function nameFunctionParameter description
lv_color_lighten(c, lvl)Lighten colorlvl=0 (unchanged) ~ 255 (all white)
lv_color_darken(c, lvl)Darken colorlvl=0 (unchanged) ~ 255 (all black)
lv_color_change_lightness(c, lvl)Overall brightness adjustmentlvl=0 (all black), 128 (unchanged), 255 (all white)
lv_color_mix(c1, c2, ratio)Mix two colorsratio=0 (all c2), 128 (half each), 255 (all c1)

2.15.4 Transparency

LVGL uses the lv_opa_t type (based on uint8_t, with values ranging from 0 to 255) to describe transparency, which centers on the concept of "coverage": the higher the value, the less transparent the color, and the more of the underlying content it obscures.

2.15.5 Core Constants

Palette base color constants:

Constant nameCorresponding colorConstant nameCorresponding color
LV_PALETTE_REDRedLV_PALETTE_GREENGreen
LV_PALETTE_PINKPinkLV_PALETTE_LIGHT_GREENLight green
LV_PALETTE_PURPLEPurpleLV_PALETTE_LIMELime
LV_PALETTE_DEEP_PURPLEDeep purpleLV_PALETTE_YELLOWYellow
LV_PALETTE_INDIGOIndigoLV_PALETTE_AMBERAmber
LV_PALETTE_BLUEBlueLV_PALETTE_ORANGEOrange
LV_PALETTE_LIGHT_BLUELight blueLV_PALETTE_DEEP_ORANGEDeep orange
LV_PALETTE_CYANCyanLV_PALETTE_BROWNBrown
LV_PALETTE_TEALTealLV_PALETTE_BLUE_GREYBlue gray
LV_PALETTE_GREYGray--

Transparency Constants:

Constant nameValueMeaningConstant nameValueMeaning
LV_OPA_TRANSP0Fully transparentLV_OPA_6015360% opaque
LV_OPA_102510% opaque (almost transparent)LV_OPA_7017870% opaque
LV_OPA_205120% opaqueLV_OPA_8020480% opaque
LV_OPA_307630% opaqueLV_OPA_9022990% opaque (almost opaque)
LV_OPA_4010240% opaqueLV_OPA_COVER255Fully opaque (default)
LV_OPA_5012850% opaque (semi-transparent)---

2.16 Fonts and Icons

The font module of LVGL is the core of text rendering, essentially a package of "glyph bitmap set + rendering control information". All fonts are ultimately stored in the lv_font_t structure, and are bound for use via the text_font field of the widget style.

2.16.1 Core Fundamentals: Pixel Precision of Fonts (bpp)

bpp (bits per pixel, short for bits per pixel) is the most fundamental core attribute of a font, which determines the edge smoothness and memory footprint of the font:

2.16.2 Unicode and Symbol Support (Basic Text Rendering)

LVGL natively supports UTF-8 encoding Unicode characters, which serves as the foundation for multi-language and symbol rendering:

2.16.2.1 Enablement Conditions

Ensure that lv_conf.h has LV_TXT_ENC = LV_TXT_ENC_UTF8 (enabled by default), and the code files are saved in UTF-8 encoding.

2.16.2.2 Usage of Built-in Symbols

LVGL extends built-in fonts with FontAwesome icons (such as check marks, WiFi symbols, play buttons, etc.), which can be used directly via the LV_SYMBOL_XXX constants:

II. Visual Style and Resource System: GUI Skins and Creatives

2.16.3 Built-in Fonts

LVGL provides multiple types of built-in fonts, which need to be enabled via lv_conf.h using the LV_FONT_… macros, and are mainly divided into two categories: "ordinary fonts" and "special fonts":

2.16.3.1 Regular Font (Montserrat Family)

Based on the Montserrat font, it covers ASCII characters, the degree sign (U+ 00B0), bullet point (U+ 2022) and built-in symbols, offers 19 sizes ranging from 12px to 48px, and follows the naming convention of LV_FONT_MONTSERRAT_<size>(for example, LV_FONT_MONTSERRAT_16), which corresponds to the global variable lv_font_montserrat_16.

2.16.3.2 Special Font
Constant nameFeatureApplicable scenarios
LV_FONT_MONTSERRAT_28_COMPRESSED28px, 3bpp + compressed storageLarge screens with low memory
LV_FONT_DEJAVU_16_PERSIAN_HEBREW16px, supports Hebrew / Arabic / PersianMiddle Eastern language interfaces
LV_FONT_SIMSUN_16_CJK16px, includes 1000 common CJK charactersBasic CJK (Chinese, Japanese, Korean) interface
LV_FONT_UNSCII_8/168/16px, pixel style, ASCII onlyRetro pixel-style UI, low-memory devices

2.16.4 Special Rendering Features of Fonts

2.16.4.1 Bidirectional Text (BiDi) Support

Supports rendering for left-to-right (LTR) and right-to-left (RTL) languages (such as Arabic and Hebrew), as well as mixed-direction text:

2.16.4.2 Arabic / Persian Character Support

The character forms of such languages vary depending on their position (isolated/initial/medial/final), and LVGL enables LV_USE_ARABIC_PERSIAN_CHARS to support this rule, but there are 3 limitations:

2.16.4.3 Subpixel Rendering

By leveraging the RGB sub-pixel layout of screen pixels, the horizontal resolution is tripled, resulting in smoother font edges:

Serial No.

Functions

Description

Enabling / Configuration Method

Restrictions / Notes

1

Bidirectional Text (BiDi) Support

It supports left-to-right (LTR) and right-to-left (RTL) languages (such as Arabic and Hebrew), and also supports mixed-direction text rendering.

Enable LV_USE_BIDI in lv_conf.h; you can set the base direction for a widget via lv_obj_set_base_dir (obj, dir); common constants include LV_BASE_DIR_LTR, LV_BASE_DIR_RTL, and LV_BASE_DIR_AUTO.

In RTL mode, the control creation position, Tab bar, checkboxes and other elements will automatically adapt to the right-to-left layout.

2

Arabic / Persian character support

It supports the character forms of such languages that vary according to their position (isolated / initial / medial / final).

Enable LV_USE_ARABIC_PERSIAN_CHARS in lv_conf.h.

Only supports the display of static text such as Label, and does not support text input boxes (Text Area); only processes dynamic text (e. g., lv_label_set_text ()), and does not process static text (e. g., lv_label_set_text_static ()); the processed form will be returned when obtaining the text.

3

Subpixel Rendering

By leveraging the RGB sub-pixel layout of screen pixels, it improves the horizontal resolution to make font edges more delicate.

When generating fonts, check the "Subpixel" option (in the online converter), or add the --lcd flag in the command line; you can configure LV_SUBPX_BGR to match the subpixel order of the display screen.

Font memory increases by approximately 3x; it is necessary to match the sub-pixel order (RGB / BGR) of the screen.

4

Subset Font

Compresses font bitmaps to reduce memory usage, making it suitable for large-sized fonts.

Check the "Compressed" option in the online converter; this feature is enabled by default in the command line, and you can use --no-compress to disable it.

The rendering speed is approximately 30% slower; it is recommended to only compress large-sized, infrequently used fonts; the compression effect is more significant for large-size / high-bpp fonts.

5

Kerning

Adjust the spacing between specific character pairs (e. g., "AV", "Ta") to enhance the visual appeal of typesetting.

Generated by the online converter by default; add --no-kerning in the command line to disable it;lv_font_set_kerning () can be used at runtime.

FreeType integration is not supported for the time being; Tiny TTF supports GPOS/Kern tables.

2.16.5 Font Extension (Custom / Dynamic Loading)

Serial No.

Functions

Description

Implementation / Configuration

Restrictions / Notes

1

Add New Fonts (Core Extension Method)

LVGL does not natively support vector fonts such as TTF and WOFF, which need to be converted into bitmap fonts before use.

① Online converter: Configure dimensions, bpp, and character range, then generate a C file to add to the project; ② Offline converter (Node.js): Suitable for batch and local generation;

③ Built-in Font Script (Python): Generates Montserrat fonts with custom dimensions and character ranges.

It must be converted to a bitmap font before use; the font size increases significantly with the dimensions and character set.

2

Add New Symbol

Extend custom symbols (such as USB, battery icons) based on FontAwesome.

① Obtain the Unicode ID of the symbol;

② Import FontAwesome in the online converter and specify the corresponding Unicode; ③ Generate the font file;

④ Define and use constants after converting Unicode to UTF-8.

Ensure that the corresponding Unicode characters are included in the font, and different encoding formats are converted correctly.

3

Load fonts at runtime

Supports dynamic font loading from files or memory (not embedded at compile time).

Enable the LVGL file system;

① File loading: lv_binfont_create ("path/font. bin");

② Memory loading: lv_binfont_create_from_buffer (buf, size); call lv_binfont_destroy () to release resources after use.

The font needs to be converted to. bin format in advance; memory must be managed manually to avoid leaks.

4

Custom Font Engine

Replace the LVGL built-in bitmap font engine (e. g., integrate FreeType to render TTF).

Implement two core callbacks:

① get_glyph_dsc_cb (returns glyph dimensions, offsets, etc.);

② get_glyph_bitmap_cb (returns glyph bitmap data).

It features high implementation complexity, and requires handling issues such as caching and Performance optimization on your own.

5

Font Fallback

When the primary font lacks certain characters, it will automatically render them using a fallback font, which is suitable for multi-language and multi-symbol scenarios.

Settings: Main Font -> fallback = Fallback Font; chaining fallback is supported (the fallback font can further set its own fallback).

Excessively long fallback chains will impact performance; it is necessary to properly plan the font coverage.

2.16.6 Core Constant Table

Constant nameValue / MeaningApplicable scenarios
LV_BASE_DIR_LTR0, left to right (default)Chinese / English / European languages
LV_BASE_DIR_RTL1, right to leftArabic / Hebrew / Persian
LV_BASE_DIR_AUTO2, auto-detectMixed-direction text
2.16.6.2 Built-in Common Font Constants (Montserrat Family)
Constant nameSize (px)Constant nameSize (px)
LV_FONT_MONTSERRAT_1212LV_FONT_MONTSERRAT_3030
LV_FONT_MONTSERRAT_1414LV_FONT_MONTSERRAT_3232
LV_FONT_MONTSERRAT_1616LV_FONT_MONTSERRAT_3434
LV_FONT_MONTSERRAT_1818LV_FONT_MONTSERRAT_3636
LV_FONT_MONTSERRAT_2020LV_FONT_MONTSERRAT_3838
LV_FONT_MONTSERRAT_2222LV_FONT_MONTSERRAT_4040
LV_FONT_MONTSERRAT_2424LV_FONT_MONTSERRAT_4242
LV_FONT_MONTSERRAT_2626LV_FONT_MONTSERRAT_4444
LV_FONT_MONTSERRAT_2828LV_FONT_MONTSERRAT_46/4846/48
Constant nameMeaningFont bpp options
LV_OPA_TRANSPFully transparent (0)1/2/4/8
LV_OPA_COVERFully opaque (255)-

2.17 Image

The "image" in LVGL is essentially a combination of bitmap data and metadata. The metadata contains key information such as dimensions and color format, and its core design revolves around "lightweight storage", "format adaptability" and "high-performance rendering" to adapt to the memory and hardware constraints of embedded scenarios.

2.17.1 Core Fundamentals: Image Storage Methods

LVGL supports two image storage formats, which are respectively adapted to the scenarios of "fixed resources" and "flexible update":

Storage methodStorage locationCore carrierAdvantagesDisadvantages
Variable storageInternal memory (RAM/ROM)lv_image_dsc_t structLinked into the program at compile time, resource usage is controllable; no extra IO needed for renderingChanging an image requires recompiling the project
File storageExternal storage (SD card / SPI Flash)LVGL file system driverImages can be updated independently without rebuilding the main programMust be loaded into RAM before rendering, IO takes time; low resource friendliness

lv_image_dsc_t Core Structure (Variable Storage Foundation)

This struct serves as the core encapsulation of memory images, with the following key fields:

2.17.2 Core Foundation: Color Format (Underlying Rules for Image Rendering)

The color format determines the encoding method of image pixels. LVGL divides them into two categories: "built-in formats" and "raw formats", which are the key to adapting images to hardware:

2.17.2.1 Built-in Color Formats (Directly Supported for Rendering)
Format categorySpecific typeCore featuresApplicable scenarios
Native formatLV_COLOR_FORMAT_NATIVEStores RGB data at the color depth configured in LVGLOrdinary color images, matching the hardware's native color depth
Native with AlphaLV_COLOR_FORMAT_NATIVE_WITH_ALPHANative format + one Alpha byte per pixelColor images with transparency
Indexed color formatLV_COLOR_FORMAT_I1/I2/I4/I8Palette mode (2/4/16/256 colors), each pixel takes 1/2/4/8 bitsImages with low color depth and few colors (such as icons)
Alpha-only formatLV_COLOR_FORMAT_A1/A2/A4/A8Stores only Alpha values, color is determined by style.img_recolorSingle-tone images whose color can change dynamically (such as font-type bitmaps)
2.17.2.2 Byte Storage Order in Native Format

Under different color depths, LV_COLOR_FORMAT_NATIVE the byte arrangement rule is as follows:

2.17.2.3 Original Format (External Decoder Required)

For common formats such as PNG and JPG that are not directly supported by LVGL, it needs to be used with the "image decoder":

2.17.3 Adding and Using Images

2.17.3.1 Two Methods for Adding Images
2.17.3.2 Core Logic of Image Usage

Render via the lv_image control, simply set the data source:

2.17.4 Image Decoder

LVGL natively only supports indexed color, native color, etc. , and external decoding libraries need to be integrated for PNG/JPG formats:

2.17.5 Image Post-processing

Adjust the image data after decoding (such as alpha premultiplication and row alignment) to adapt to hardware requirements; mark the processing status to avoid repeated operations.

2.17.6 Image Cache (Performance optimization)

2.17.7 Core Constants

CategoryConstant / MacroCore meaning
Color formatLV_COLOR_FORMAT_NATIVENative RGB, ordinary color image
NATIVE_WITH_ALPHANative RGB+Alpha, color image with transparency
I1/I2/I4/I8Indexed color, low color depth image
A1/A2/A4/A8Alpha only, single-tone image
RAW/RAW_ALPHANeeds decoding, PNG/JPG (RAW_ALPHA has transparency)
CacheLV_CACHE_DEF_SIZEDefault cache size (0, disabled)
PTR/FILECache source: memory pointer / file path
Decoder return valueLV_RESULT_OKOperation succeeded
LV_RESULT_INVALIDFormat not supported

Version Record

Version Number

Modifier

Time

Content

v1.0

Li Zisheng

2026/03/23

Initialize the document.

v1.1

Li Zisheng

2026/04/07

Fix the table issue.