1# Benchmark demo
2
3## Overview
4
5The benchmark demo tests the performance in various cases.
6For example rectangle, border, shadow, text, image blending, image transformation, blending modes, etc.
7All tests are repeated with 50% opacity.
8
9The size and position of the objects during testing are set with a pseudo random number to make the benchmark repeatable.
10
11On to top of the screen the title of the current test step, and the result of the previous step is displayed.
12
13## Run the benchmark
14- In `lv_conf.h` or equivalent places set `LV_USE_DEMO_BENCHMARK 1`
15- After `lv_init()` and initializing the drivers call `lv_demo_benchmark()`
16- If you only want to run a specific scene for any purpose (e.g. debug, performance optimization etc.), you can call `lv_demo_benchmark_run_scene()` instead of `lv_demo_benchmark()`and pass the scene number.
17- If you enabled trace output by setting macro `LV_USE_LOG` to `1` and trace level `LV_LOG_LEVEL` to `LV_LOG_LEVEL_USER` or higher, benchmark results are printed out in `csv` format.
18- If you want to know when the testing is finished, you can register a callback function via `lv_demo_benchmark_register_finished_handler()` before calling `lv_demo_benchmark()` or `lv_demo_benchmark_run_scene()`.
19- If you want to know the maximum rendering performance of the system, call `lv_demo_benchmark_set_max_speed(true)` before `lv_demo_benchmark()`.
20
21## Interpret the result
22
23The FPS is measured like this:
24- load the next step
25- in the display driver's `monitor_cb` accumulate the time-to-render and the number of cycles
26- measure for 1 second
27- calculate `FPS = time_sum / render_cnt`
28
29Note that it can result in very high FPS results for simple cases.
30E.g. if some simple rectangles are drawn in 5 ms, the benchmark will tell it's 200 FPS.
31So it ignores `LV_DISP_REFR_PERIOD` which tells LVGL how often it should refresh the screen.
32In other words, the benchmark shows the FPS from the pure rendering time.
33
34By default, only the changed areas are refreshed. It means if only a few pixels are changed in 1 ms the benchmark will show 1000 FPS. To measure the performance with full screen refresh uncomment `lv_obj_invalidate(lv_scr_act())` in `monitor_cb()` in `lv_demo_benchmark.c`.
35
36![LVGL benchmark running](screenshot1.png)
37
38If you are doing performance analysis for 2D image processing optimization, LCD latency (flushing data to LCD) introduced by `disp_flush()` might dilute the performance results of the LVGL drawing process, hence make it harder to see your optimization results (gain or loss). To avoid such problem, please:
39
401. Use a flag to control the LCD flushing inside `disp_flush()`. For example:
41
42```c
43volatile bool disp_flush_enabled = true;
44
45/* Enable updating the screen (the flushing process) when disp_flush() is called by LVGL
46 */
47void disp_enable_update(void)
48{
49    disp_flush_enabled = true;
50}
51
52/* Disable updating the screen (the flushing process) when disp_flush() is called by LVGL
53 */
54void disp_disable_update(void)
55{
56    disp_flush_enabled = false;
57}
58
59static void disp_flush(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p)
60{
61    if(disp_flush_enabled) {
62        GLCD_DrawBitmap(area->x1,                   //!< x
63                        area->y1,                   //!< y
64                        area->x2 - area->x1 + 1,    //!< width
65                        area->y2 - area->y1 + 1,    //!< height
66                        (const uint8_t *)color_p);
67    }
68
69    /*IMPORTANT!!!
70     *Inform the graphics library that you are ready with the flushing*/
71    lv_disp_flush_ready(disp_drv);
72}
73```
74
752. Disable flushing before calling `lv_demo_benchmark()` or `lv_demo_benchmark_run_scene()`, for example:
76
77```c
78extern void disp_enable_update(void);
79extern void disp_disable_update(void);
80
81static void on_benchmark_finished(void)
82{
83    disp_enable_update();
84}
85
86int main(void)
87{
88    lv_init();
89    lv_port_disp_init();
90    lv_port_indev_init();
91
92    LV_LOG("Running LVGL Benchmark...");
93    LV_LOG("Please stand by...");
94    LV_LOG("NOTE: You will NOT see anything until the end.");
95
96    disp_disable_update();
97
98    lv_demo_benchmark_set_finished_cb(&on_benchmark_finished);
99    lv_demo_benchmark_set_max_speed(true);
100    lv_demo_benchmark();
101
102    //lv_demo_benchmark_run_scene(43);      // run scene no 31
103
104    ...
105    while(1){
106        lv_timer_handler();                 //! run lv task at the max speed
107    }
108}
109```
110
111
112
1133. Alternatively, you can use trace output to get the benchmark results in csv format by:
114   - Setting macro `LV_USE_LOG` to `1`
115   - Setting trace level `LV_LOG_LEVEL` to `LV_LOG_LEVEL_USER` or higher.
116
117
118
119
120## Result summary
121In the end, a table is created to display measured FPS values.
122
123On top of the summary screen, the "Weighted FPS" value is shown.
124In this, the result of the more common cases are taken into account with a higher weight.
125
126"Opa. speed" shows the speed of the measurements with opacity compared to full opacity.
127E.g. "Opa. speed = 90%" means that rendering with opacity is 10% slower.
128
129In the first section of the table, "Slow but common cases", those cases are displayed which are considered common but were slower than 20 FPS.
130
131Below this in the "All cases section" all the results are shown. The < 10 FPS results are shown with red, the >= 10 but < 20 FPS values are displayed with orange.
132
133
134![LVGL benchmark result summary](https://github.com/lvgl/lvgl/tree/master/demos/benchmark/screenshot2.png?raw=true)
135