quantum_painter_lvgl.md (3146B)
1 # Quantum Painter LVGL Integration {#lvgl} 2 3 LVGL (Light and Versatile Graphics Library) is an open-source graphics library providing everything you need to create an embedded GUI for your board with easy-to-use graphical elements. 4 5 LVGL integrates with [Quantum Painter's](quantum_painter) API and drivers to render to the display, the hardware supported by Quantum Painter is also supported by LVGL. 6 7 ::: tip 8 Keep in mind that enabling the LVGL integration has a big impact in firmware size, it is recommended to use a supported MCU with >256 kB of flash space. 9 ::: 10 11 To learn more about LVGL and how to use it please take a look at their [official documentation](https://docs.lvgl.io/8.2/intro/) 12 13 ## Enabling LVGL {#lvgl-enabling} 14 To enable LVGL to be built into your firmware, add the following to `rules.mk`: 15 16 ```make 17 QUANTUM_PAINTER_ENABLE = yes 18 QUANTUM_PAINTER_DRIVERS = ...... 19 QUANTUM_PAINTER_LVGL_INTEGRATION = yes 20 ``` 21 To configure the Quantum Painter Display Drivers please read the [Quantum Painter Display Drivers](quantum_painter#quantum-painter-drivers) section. 22 23 ## Quantum Painter LVGL API {#lvgl-api} 24 25 ### Quantum Painter LVGL Attach {#lvgl-api-init} 26 27 ```c 28 bool qp_lvgl_attach(painter_device_t device); 29 ``` 30 31 The `qp_lvgl_attach` function is used to set up LVGL with the supplied display, and requires an already configured display. 32 33 ```c 34 static painter_device_t display; 35 void keyboard_post_init_kb(void) { 36 display = qp_make_.......; // Create the display 37 qp_init(display, QP_ROTATION_0); // Initialise the display 38 39 if (qp_lvgl_attach(display)) { // Attach LVGL to the display 40 ...Your code to draw // Run LVGL specific code to draw 41 } 42 } 43 ``` 44 To init. the display please read the [Display Initialisation](quantum_painter#quantum-painter-api-init) section. 45 46 ::: warning 47 Attaching LVGL to a display means LVGL subsequently "owns" the display. Using standard Quantum Painter drawing operations with the display after LVGL attachment will likely result in display artifacts. 48 ::: 49 50 ### Quantum Painter LVGL Detach {#lvgl-api-detach} 51 52 ```c 53 void qp_lvgl_detach(void) 54 ``` 55 56 The `qp_lvgl_detach` function stops the internal LVGL ticks and releases resources related to it. 57 58 ## Enabling/Disabling LVGL features {#lvgl-configuring} 59 60 You can overwrite LVGL specific features in your `lv_conf.h` file. 61 62 ## Changing the LVGL task frequency 63 64 When LVGL is running, your keyboard's responsiveness may decrease, causing missing keystrokes or encoder rotations, especially during the animation of dynamically-generated content. This occurs because LVGL operates as a scheduled task with a default task rate of five milliseconds. While a fast task rate is advantageous when LVGL is responsible for detecting and processing inputs, it can lead to excessive recalculations of displayed content, which may slow down QMK's matrix scanning. If you rely on QMK instead of LVGL for processing inputs, it can be beneficial to increase the time between calls to the LVGL task handler to better match your preferred display update rate. To do this, add this to your `config.h`: 65 66 ```c 67 #define QP_LVGL_TASK_PERIOD 40 68 ```