acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
Log | Files | Refs | Archive | README | LICENSE

display.md (14381B)

      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/porting/display.md
      4 ```
      5 # Display interface
      6 
      7 To register a display for LVGL, a `lv_disp_draw_buf_t` and a `lv_disp_drv_t` variable have to be initialized.
      8 - `lv_disp_draw_buf_t` contains internal graphic buffer(s) called draw buffer(s).
      9 - `lv_disp_drv_t` contains callback functions to interact with the display and manipulate low level drawing behavior.
     10 
     11 ## Draw buffer
     12 
     13 Draw buffer(s) are simple array(s) that LVGL uses to render the screen content.
     14 Once rendering is ready the content of the draw buffer is sent to the display using the `flush_cb` function set in the display driver (see below).
     15 
     16 A draw buffer can be initialized via a `lv_disp_draw_buf_t` variable like this:
     17 ```c
     18 /*A static or global variable to store the buffers*/
     19 static lv_disp_draw_buf_t disp_buf;
     20 
     21 /*Static or global buffer(s). The second buffer is optional*/
     22 static lv_color_t buf_1[MY_DISP_HOR_RES * 10];
     23 static lv_color_t buf_2[MY_DISP_HOR_RES * 10];
     24 
     25 /*Initialize `disp_buf` with the buffer(s). With only one buffer use NULL instead buf_2 */
     26 lv_disp_draw_buf_init(&disp_buf, buf_1, buf_2, MY_DISP_HOR_RES*10);
     27 ```
     28 
     29 Note that `lv_disp_draw_buf_t` must be a static, global or dynamically allocated variable. It cannot be a local variable as they are destroyed upon end of scope.
     30 
     31 As you can see above, the draw buffer may be smaller than the screen. In this case, larger areas are redrawn in smaller segments that fit into the draw buffer(s).
     32 If only a small area changes (e.g. a button is pressed) then only that area will be refreshed.
     33 
     34 A larger buffer results in better performance but above 1/10 screen sized buffer(s) there is no significant performance improvement.
     35 Therefore it's recommended to choose the size of the draw buffer(s) to be at least 1/10 screen sized.
     36 
     37 ## Buffering modes
     38 
     39 There are several settings to adjust the number draw buffers and buffering/refreshing modes.
     40 
     41 You can measure the performance of different configurations using the [benchmark example](https://github.com/lvgl/lvgl/tree/master/demos/benchmark).
     42 
     43 ### One buffer
     44 If only one buffer is used LVGL draws the content of the screen into that draw buffer and sends it to the display.
     45 LVGL then needs to wait until the content of the buffer is sent to the display before drawing something new in it.
     46 
     47 ### Two buffers
     48 If two buffers  are used LVGL can draw into one buffer while the content of the other buffer is sent to the display in the background.
     49 DMA or other hardware should be used to transfer data to the display so the MCU can continue drawing.
     50 This way, the rendering and refreshing of the display become parallel operations.
     51 
     52 ### Full refresh
     53 In the display driver (`lv_disp_drv_t`) enabling the `full_refresh` bit will force LVGL to always redraw the whole screen. This works in both *one buffer* and *two buffers* modes.
     54 If `full_refresh` is enabled and two screen sized draw buffers are provided, LVGL's display handling works like "traditional" double buffering.
     55 This means the `flush_cb` callback only has to update the address of the framebuffer (`color_p` parameter).
     56 This configuration should be used if the MCU has an LCD controller peripheral and not with an external display controller (e.g. ILI9341 or SSD1963) accessed via serial link. The latter will generally be too slow to maintain high frame rates with full screen redraws.
     57 
     58 ### Direct mode
     59 If the `direct_mode` flag is enabled in the display driver LVGL will draw directly into a **screen sized frame buffer**. That is the draw buffer(s) needs to be screen sized.
     60 It this case `flush_cb` will be called only once when all dirty areas are redrawn.
     61 With `direct_mode` the frame buffer always contains the current frame as it should be displayed on the screen.
     62 If 2 frame buffers are provided as draw buffers LVGL will alter the buffers but always draw only the dirty areas.
     63 Therefore the 2 buffers needs to synchronized in `flush_cb` like this:
     64 1. Display the frame buffer pointed by `color_p`
     65 2. Copy the redrawn areas from `color_p` to the other buffer.
     66 
     67 The get the redrawn areas to copy use the following functions
     68 `_lv_refr_get_disp_refreshing()` returns the display being refreshed
     69 `disp->inv_areas[LV_INV_BUF_SIZE]` contains the invalidated areas
     70 `disp->inv_area_joined[LV_INV_BUF_SIZE]` if 1 that area was joined into another one and should be ignored
     71 `disp->inv_p` number of valid elements in `inv_areas`
     72 
     73 ## Display driver
     74 
     75 Once the buffer initialization is ready a `lv_disp_drv_t` display driver needs to be:
     76 1. initialized with `lv_disp_drv_init(&disp_drv)`
     77 2. its fields need to be set
     78 3. it needs to be registered in LVGL with `lv_disp_drv_register(&disp_drv)`
     79 
     80 Note that `lv_disp_drv_t` also needs to be a static, global or dynamically allocated variable.
     81 
     82 ### Mandatory fields
     83 In the most simple case only the following fields of `lv_disp_drv_t` need to be set:
     84 - `draw_buf` pointer to an initialized `lv_disp_draw_buf_t` variable.
     85 - `hor_res` horizontal resolution of the display in pixels.
     86 - `ver_res` vertical resolution of the display in pixels.
     87 - `flush_cb` a callback function to copy a buffer's content to a specific area of the display.
     88 `lv_disp_flush_ready(&disp_drv)` needs to be called when flushing is ready.
     89 LVGL might render the screen in multiple chunks and therefore call `flush_cb` multiple times. To see if the current one is the last chunk of rendering use `lv_disp_flush_is_last(&disp_drv)`.
     90 
     91 ### Optional fields
     92 There are some optional display driver data fields:
     93 - `physical_hor_res` horizontal resolution of the full / physical display in pixels. Only set this when _not_ using the full screen (defaults to -1 / same as `hor_res`).
     94 - `physical_ver_res` vertical resolution of the full / physical display in pixels. Only set this when _not_ using the full screen (defaults to -1 / same as `ver_res`).
     95 - `offset_x` horizontal offset from the full / physical display in pixels. Only set this when _not_ using the full screen (defaults to 0).
     96 - `offset_y` vertical offset from the full / physical display in pixels. Only set this when _not_ using the full screen (defaults to 0).
     97 - `color_chroma_key` A color which will be drawn as transparent on chrome keyed images. Set to `LV_COLOR_CHROMA_KEY` from `lv_conf.h` by default.
     98 - `anti_aliasing` use anti-aliasing (edge smoothing). Enabled by default if `LV_COLOR_DEPTH` is set to at least 16 in `lv_conf.h`.
     99 - `rotated` and `sw_rotate` See the [Rotation](#rotation) section below.
    100 - `screen_transp` if `1` the screen itself can have transparency as well. `LV_COLOR_SCREEN_TRANSP` must be enabled in `lv_conf.h` and `LV_COLOR_DEPTH` must be 32.
    101 - `user_data` A custom `void` user data for the driver.
    102 - `full_refresh` always redrawn the whole screen (see above)
    103 - `direct_mode` draw directly into the frame buffer (see above)
    104 
    105 Some other optional callbacks to make it easier and more optimal to work with monochrome, grayscale or other non-standard RGB displays:
    106 - `rounder_cb` Round the coordinates of areas to redraw. E.g. a 2x2 px can be converted to 2x8.
    107 It can be used if the display controller can refresh only areas with specific height or width (usually 8 px height with monochrome displays).
    108 - `set_px_cb` a custom function to write the draw buffer. It can be used to store the pixels more compactly in the draw buffer if the display has a special color format. (e.g. 1-bit monochrome, 2-bit grayscale etc.)
    109 This way the buffers used in `lv_disp_draw_buf_t` can be smaller to hold only the required number of bits for the given area size. Note that rendering with `set_px_cb` is slower than normal rendering.
    110 - `monitor_cb` A callback function that tells how many pixels were refreshed and in how much time. Called when the last chunk is rendered and sent to the display.
    111 - `clean_dcache_cb` A callback for cleaning any caches related to the display.
    112 - `render_start_cb` A callback function that notifies the display driver that rendering has started. It also could be used to wait for VSYNC to start rendering. It's useful if rendering is faster than a VSYNC period.
    113 
    114 LVGL has built-in support to several GPUs (see `lv_conf.h`) but if something else is required these functions can be used to make LVGL use a GPU:
    115 - `gpu_fill_cb` fill an area in the memory with a color.
    116 - `gpu_wait_cb` if any GPU function returns while the GPU is still working, LVGL will use this function when required to make sure GPU rendering is ready.
    117 
    118 ### Examples
    119 All together it looks like this:
    120 ```c
    121 static lv_disp_drv_t disp_drv;          /*A variable to hold the drivers. Must be static or global.*/
    122 lv_disp_drv_init(&disp_drv);            /*Basic initialization*/
    123 disp_drv.draw_buf = &disp_buf;          /*Set an initialized buffer*/
    124 disp_drv.flush_cb = my_flush_cb;        /*Set a flush callback to draw to the display*/
    125 disp_drv.hor_res = 320;                 /*Set the horizontal resolution in pixels*/
    126 disp_drv.ver_res = 240;                 /*Set the vertical resolution in pixels*/
    127 
    128 lv_disp_t * disp;
    129 disp = lv_disp_drv_register(&disp_drv); /*Register the driver and save the created display objects*/
    130 ```
    131 
    132 Here are some simple examples of the callbacks:
    133 ```c
    134 void my_flush_cb(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p)
    135 {
    136     /*The most simple case (but also the slowest) to put all pixels to the screen one-by-one
    137      *`put_px` is just an example, it needs to implemented by you.*/
    138     int32_t x, y;
    139     for(y = area->y1; y <= area->y2; y++) {
    140         for(x = area->x1; x <= area->x2; x++) {
    141             put_px(x, y, *color_p);
    142             color_p++;
    143         }
    144     }
    145 
    146     /* IMPORTANT!!!
    147      * Inform the graphics library that you are ready with the flushing*/
    148     lv_disp_flush_ready(disp_drv);
    149 }
    150 
    151 void my_gpu_fill_cb(lv_disp_drv_t * disp_drv, lv_color_t * dest_buf, const lv_area_t * dest_area, const lv_area_t * fill_area, lv_color_t color);
    152 {
    153     /*It's an example code which should be done by your GPU*/
    154     uint32_t x, y;
    155     dest_buf += dest_width * fill_area->y1; /*Go to the first line*/
    156 
    157     for(y = fill_area->y1; y < fill_area->y2; y++) {
    158         for(x = fill_area->x1; x < fill_area->x2; x++) {
    159             dest_buf[x] = color;
    160         }
    161         dest_buf+=dest_width;    /*Go to the next line*/
    162     }
    163 }
    164 
    165 
    166 void my_rounder_cb(lv_disp_drv_t * disp_drv, lv_area_t * area)
    167 {
    168   /* Update the areas as needed.
    169    * For example it makes the area to start only on 8th rows and have Nx8 pixel height.*/
    170    area->y1 = area->y1 & 0x07;
    171    area->y2 = (area->y2 & 0x07) + 8;
    172 }
    173 
    174 void my_set_px_cb(lv_disp_drv_t * disp_drv, uint8_t * buf, lv_coord_t buf_w, lv_coord_t x, lv_coord_t y, lv_color_t color, lv_opa_t opa)
    175 {
    176    /* Write to the buffer as required for the display.
    177     * For example it writes only 1-bit for monochrome displays mapped vertically.*/
    178    buf += buf_w * (y >> 3) + x;
    179    if(lv_color_brightness(color) > 128) (*buf) |= (1 << (y % 8));
    180    else (*buf) &= ~(1 << (y % 8));
    181 }
    182 
    183 void my_monitor_cb(lv_disp_drv_t * disp_drv, uint32_t time, uint32_t px)
    184 {
    185   printf("%d px refreshed in %d ms\n", time, ms);
    186 }
    187 
    188 void my_clean_dcache_cb(lv_disp_drv_t * disp_drv, uint32)
    189 {
    190   /* Example for Cortex-M (CMSIS) */
    191   SCB_CleanInvalidateDCache();
    192 }
    193 ```
    194 
    195 ## Other options
    196 
    197 ### Rotation
    198 
    199 LVGL supports rotation of the display in 90 degree increments. You can select whether you'd like software rotation or hardware rotation.
    200 
    201 If you select software rotation (`sw_rotate` flag set to 1), LVGL will perform the rotation for you. Your driver can and should assume that the screen width and height have not changed. Simply flush pixels to the display as normal. Software rotation requires no additional logic in your `flush_cb` callback.
    202 
    203 There is a noticeable amount of overhead to performing rotation in software. Hardware rotation is available to avoid unwanted slowdowns. In this mode, LVGL draws into the buffer as if your screen width and height were swapped. You are responsible for rotating the provided pixels yourself.
    204 
    205 The default rotation of your display when it is initialized can be set using the `rotated` flag. The available options are `LV_DISP_ROT_NONE`, `LV_DISP_ROT_90`, `LV_DISP_ROT_180`, or `LV_DISP_ROT_270`. The rotation values are relative to how you would rotate the physical display in the clockwise direction. Thus, `LV_DISP_ROT_90` means you rotate the hardware 90 degrees clockwise, and the display rotates 90 degrees counterclockwise to compensate.
    206 
    207 (Note for users upgrading from 7.10.0 and older: these new rotation enum values match up with the old 0/1 system for rotating 90 degrees, so legacy code should continue to work as expected. Software rotation is also disabled by default for compatibility.)
    208 
    209 Display rotation can also be changed at runtime using the `lv_disp_set_rotation(disp, rot)` API.
    210 
    211 Support for software rotation is a new feature, so there may be some glitches/bugs depending on your configuration. If you encounter a problem please open an issue on [GitHub](https://github.com/lvgl/lvgl/issues).
    212 
    213 ### Decoupling the display refresh timer
    214 Normally the dirty (a.k.a invalid) areas are checked and redrawn in every `LV_DISP_DEF_REFR_PERIOD` milliseconds (set in `lv_conf.h`).
    215 However, in some cases you might need more control on when the display refreshing happen, for example to synchronize rendering with VSYNC or the TE signal.
    216 
    217 You can do this in the following way:
    218 ```c
    219 /*Delete the original display refresh timer*/
    220 lv_timer_del(disp->refr_timer);
    221 disp->refr_timer = NULL;
    222 
    223 
    224 /*Call this anywhere you want to refresh the dirty areas*/
    225 _lv_disp_refr_timer(NULL);
    226 ```
    227 
    228 If you have multiple displays call `lv_disp_set_deafult(disp1);` to select the display to refresh before `_lv_disp_refr_timer(NULL);`.
    229 
    230 Note that `lv_timer_handler()` and `_lv_disp_refr_timer()` can not run at the same time.
    231 
    232 If the performance monitor is enabled, the value of `LV_DISP_DEF_REFR_PERIOD` needs to be set to be consistent with the refresh period of the display to ensure that the statistical results are correct.
    233 
    234 ## Further reading
    235 
    236 - [lv_port_disp_template.c](https://github.com/lvgl/lvgl/blob/master/examples/porting/lv_port_disp_template.c) for a template for your own driver.
    237 - [Drawing](/overview/drawing) to learn more about how rendering works in LVGL.
    238 - [Display features](/overview/display) to learn more about higher level display features.
    239 
    240 ## API
    241 
    242 ```eval_rst
    243 
    244 .. doxygenfile:: lv_hal_disp.h
    245   :project: lvgl
    246 
    247 ```